class_list_op 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d357785ffdda8c49dadf2b3220b8359ed4255ab79a95e4397787d8b9f8693909
+  data.tar.gz: 3c3c1b9f81125e785106fb069a2a5da4bb282fdea1de8edf2eb1429f8d44ff1e
+SHA512:
+  metadata.gz: 60936a499d423937b8f4ab088619500362f2c693f8d91632f6e7bd239db8e0a5aef2f8c9ec31155bce37f0d3a6749eb09eebacd0774af77a7411de4798fea943
+  data.tar.gz: '0641594aaa67ad7fab30707d306c9eef87dd78c03d452a018e159c6c5b60c06a2f8ef767fa779f59a09c26001e706c20b6a2d4342fffd9d2735c81b89d99f2cf'

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-04-05
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"class_list_op" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["alexander.s.fokin@gmail.com"](mailto:"alexander.s.fokin@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alexander
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,120 @@
+# class_list_op
+
+`class_list_op` is a rendering-agnostic Ruby gem for deterministic CSS class token composition.
+
+It does not know anything about Rails, ViewComponent, Phlex, Tailwind, or HTML rendering. It only:
+
+- normalizes class input
+- applies class operations
+- returns tokens or a resolved string
+
+Public namespace:
+
+```ruby
+ClassList
+```
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add class_list_op
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install class_list_op
+```
+
+## Usage
+
+```ruby
+require "class_list_op"
+
+ClassList.normalize(["flex gap-4", ["mb-2", nil, ""]])
+# => ["flex", "gap-4", "mb-2"]
+
+ClassList.resolve("flex gap-4", add: "mb-4")
+# => "flex gap-4 mb-4"
+
+ClassList.resolve("flex gap-4", remove: "gap-4")
+# => "flex"
+
+ClassList.resolve("flex gap-4", replace: "mb-4")
+# => "mb-4"
+
+ClassList.call("flex gap-4", add: :hidden)
+# => "flex gap-4 hidden"
+
+list = ClassList.list("flex gap-4")
+updated = list.remove("gap-4").add("mb-4")
+
+list.to_s
+# => "flex gap-4"
+
+updated.tokens
+# => ["flex", "mb-4"]
+```
+
+### Supported inputs
+
+`ClassList.normalize` and operation values accept:
+
+- `String`
+- `Array`
+- `Symbol`
+- `nil`
+
+Normalization rules:
+
+- `nil` is ignored
+- strings are split by whitespace
+- arrays are flattened recursively
+- empty strings are ignored
+- unsupported types raise `ClassList::InvalidInputError`
+
+### Operations
+
+Supported operations:
+
+- `add`
+- `remove`
+- `replace`
+
+Rules:
+
+- `replace` cannot be combined with `add` or `remove`
+- operations are applied in this order: `base -> remove -> add -> uniq`
+- deduplication is stable and keeps the first occurrence
+
+Example for component builders:
+
+```ruby
+defaults = "cols w-full md:flex md:flex-row md:space-x-4"
+
+ClassList.resolve(defaults, add: "mb-4")
+# => "cols w-full md:flex md:flex-row md:space-x-4 mb-4"
+
+ClassList.resolve(defaults, remove: "md:space-x-4", add: "md:space-x-6")
+# => "cols w-full md:flex md:flex-row md:space-x-6"
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/alexander-fokin/class_list_op. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/alexander-fokin/class_list_op/blob/main/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the `class_list_op` project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/alexander-fokin/class_list_op/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/class_list/errors.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module ClassList
+  Error = Class.new(StandardError)
+  InvalidInputError = Class.new(Error)
+  InvalidOperationError = Class.new(Error)
+end

data/lib/class_list/list.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module ClassList
+  class List
+    attr_reader :tokens
+
+    def initialize(base = nil)
+      @tokens = ClassList.normalize(base).freeze
+    end
+
+    def add(value)
+      self.class.from_tokens(Resolver.call(@tokens, add: value))
+    end
+
+    def remove(value)
+      self.class.from_tokens(Resolver.call(@tokens, remove: value))
+    end
+
+    def replace(value)
+      self.class.from_tokens(Resolver.call(@tokens, replace: value))
+    end
+
+    def to_s
+      @tokens.join(" ")
+    end
+
+    def inspect
+      %(#<#{self.class.name} #{to_s.inspect}>)
+    end
+
+    def self.from_tokens(tokens)
+      instance = allocate
+      instance.instance_variable_set(:@tokens, tokens.freeze)
+      instance
+    end
+  end
+end

data/lib/class_list/resolver.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module ClassList
+  module Resolver
+    ALLOWED_KEYS = %i[add remove replace].freeze
+
+    module_function
+
+    def call(base = nil, **operations)
+      validate_operations!(operations)
+
+      return uniq_tokens(Tokenizer.call(operations[:replace])) if operations.key?(:replace)
+
+      tokens = Tokenizer.call(base)
+      tokens = apply_remove(tokens, operations[:remove])
+      tokens = apply_add(tokens, operations[:add])
+
+      uniq_tokens(tokens)
+    end
+
+    def validate_operations!(operations)
+      unknown_keys = operations.keys - ALLOWED_KEYS
+
+      unless unknown_keys.empty?
+        raise InvalidOperationError, "unknown operations: #{unknown_keys.join(', ')}"
+      end
+
+      return if valid_replace_combination?(operations)
+
+      raise InvalidOperationError, "replace cannot be combined with add/remove"
+    end
+
+    def valid_replace_combination?(operations)
+      return true unless operations.key?(:replace)
+
+      (operations.keys & %i[add remove]).empty?
+    end
+
+    def apply_remove(tokens, value)
+      remove_tokens = Tokenizer.call(value)
+      return tokens if remove_tokens.empty?
+
+      tokens.reject { |token| remove_tokens.include?(token) }
+    end
+
+    def apply_add(tokens, value)
+      tokens + Tokenizer.call(value)
+    end
+
+    def uniq_tokens(tokens)
+      tokens.each_with_object([]) do |token, result|
+        result << token unless result.include?(token)
+      end
+    end
+  end
+end

data/lib/class_list/tokenizer.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module ClassList
+  module Tokenizer
+    module_function
+
+    def call(value)
+      case value
+      when nil
+        []
+      when String
+        value.split(/\s+/).reject(&:empty?)
+      when Symbol
+        [value.to_s]
+      when Array
+        value.flat_map { |item| call(item) }
+      else
+        raise InvalidInputError, "unsupported class input: #{value.class}"
+      end
+    end
+  end
+end

data/lib/class_list/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module ClassList
+  VERSION = "0.1.0"
+end

data/lib/class_list_op.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "class_list/version"
+require_relative "class_list/errors"
+require_relative "class_list/tokenizer"
+require_relative "class_list/resolver"
+require_relative "class_list/list"
+
+module ClassList
+  class << self
+    def normalize(value)
+      Tokenizer.call(value)
+    end
+
+    def tokens(base = nil, **operations)
+      Resolver.call(base, **operations)
+    end
+
+    def resolve(base = nil, **operations)
+      tokens(base, **operations).join(" ")
+    end
+
+    def call(base = nil, **operations)
+      resolve(base, **operations)
+    end
+
+    def list(base = nil)
+      List.new(base)
+    end
+  end
+end

data/sig/class_list_op.rbs

@@ -0,0 +1,32 @@
+module ClassList
+  VERSION: String
+
+  def self.normalize: (String | Symbol | Array[untyped] | nil value) -> Array[String]
+  def self.tokens: (?untyped base, **untyped operations) -> Array[String]
+  def self.resolve: (?untyped base, **untyped operations) -> String
+  def self.call: (?untyped base, **untyped operations) -> String
+  def self.list: (?untyped base) -> List
+end
+
+module ClassList::Tokenizer
+  def self.call: (String | Symbol | Array[untyped] | nil value) -> Array[String]
+end
+
+module ClassList::Resolver
+  ALLOWED_KEYS: Array[Symbol]
+  def self.call: (?untyped base, **untyped operations) -> Array[String]
+end
+
+class ClassList::List
+  @tokens: Array[String]
+
+  attr_reader tokens: Array[String]
+
+  def initialize: (?untyped base) -> void
+  def add: (String | Symbol | Array[untyped] | nil value) -> ClassList::List
+  def remove: (String | Symbol | Array[untyped] | nil value) -> ClassList::List
+  def replace: (String | Symbol | Array[untyped] | nil value) -> ClassList::List
+  def to_s: () -> String
+  def inspect: () -> String
+  def self.from_tokens: (Array[String] tokens) -> ClassList::List
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: class_list_op
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alexander
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A rendering-agnostic Ruby gem for normalizing and composing CSS class
+  tokens.
+email:
+- alexander.s.fokin@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/class_list/errors.rb
+- lib/class_list/list.rb
+- lib/class_list/resolver.rb
+- lib/class_list/tokenizer.rb
+- lib/class_list/version.rb
+- lib/class_list_op.rb
+- sig/class_list_op.rbs
+homepage: https://github.com/alexander-fokin/class_list_op
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/alexander-fokin/class_list_op
+  source_code_uri: https://github.com/alexander-fokin/class_list_op
+  changelog_uri: https://github.com/alexander-fokin/class_list_op/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.9
+specification_version: 4
+summary: Deterministic CSS class token composition for Ruby.
+test_files: []