abachrome 0.1.0 → 0.1.1

data/lib/abachrome/palette.rb

@@ -1,13 +1,26 @@
-# frozen_string_literal: true
+#
 
 module Abachrome
   class Palette
     attr_reader :colors
 
+    # Initializes a new color palette with the given colors.
+    # Automatically converts non-Color objects to Color objects by parsing them as hex values.
+    # 
+    # @param colors [Array] An array of colors to include in the palette. Each element can be
+    # either a Color object or a string-convertible object representing a hex color code.
+    # @return [Abachrome::Palette] A new palette instance containing the provided colors.
     def initialize(colors = [])
       @colors = colors.map { |c| c.is_a?(Color) ? c : Color.from_hex(c.to_s) }
     end
 
+    # Adds a color to the palette.
+    # Accepts either an Abachrome::Color object or any object that can be
+    # converted to a string and parsed as a hex color code.
+    # 
+    # @param color [Abachrome::Color, String, #to_s] The color to add to the palette.
+    # If not already an Abachrome::Color object, it will be converted using Color.from_hex
+    # @return [Abachrome::Palette] self, enabling method chaining
     def add(color)
       color = Color.from_hex(color.to_s) unless color.is_a?(Color)
       @colors << color
@@ -16,64 +29,141 @@ module Abachrome
 
     alias << add
 
+    # Removes the specified color from the palette.
+    # 
+    # @param color [Abachrome::Color, Object] The color to be removed from the palette
+    # @return [Abachrome::Palette] Returns self for method chaining
     def remove(color)
       @colors.delete(color)
       self
     end
 
+    # Clears all colors from the palette.
+    # 
+    # This method removes all stored colors in the palette. It provides a way to
+    # reset the palette to an empty state while maintaining the same palette object.
+    # 
+    # @return [Abachrome::Palette] Returns self for method chaining
     def clear
       @colors.clear
       self
     end
 
+    # Returns the number of colors in the palette.
+    # 
+    # @return [Integer] the number of colors in the palette
     def size
       @colors.size
     end
 
+    # Returns whether the palette has no colors.
+    # 
+    # @return [Boolean] true if the palette contains no colors, false otherwise
     def empty?
       @colors.empty?
     end
 
+    # Yields each color in the palette to the given block.
+    # 
+    # @param block [Proc] The block to be executed for each color in the palette.
+    # @yield [Abachrome::Color] Each color in the palette.
+    # @return [Enumerator] Returns an Enumerator if no block is given.
+    # @see Enumerable#each
     def each(&block)
       @colors.each(&block)
     end
+    # Calls the given block once for each color in the palette, passing the color and its index as parameters.
+    # 
+    # @example
+    # palette.each_with_index { |color, index| puts "Color #{index}: #{color}" }
+    # 
+    # @param block [Proc] The block to be called for each color
+    # @yield [color, index] Yields a color and its index
+    # @yieldparam color [Abachrome::Color] The color at the current position
+    # @yieldparam index [Integer] The index of the current color
+    # @return [Enumerator] If no block is given, returns an Enumerator
+    # @return [Array<Abachrome::Color>] Returns the array of colors if a block is given
     def each_with_index(&block)
       @colors.each_with_index(&block)
     end
 
+    # Maps the palette by applying a block to each color.
+    # 
+    # @param block [Proc] A block that takes a color and returns a new color.
+    # @return [Abachrome::Palette] A new palette with the mapped colors.
+    # @example
+    # # Convert all colors in palette to grayscale
+    # palette.map { |color| color.grayscale }
     def map(&block)
       self.class.new(@colors.map(&block))
     end
 
+    # Returns a duplicate of the internal colors array.
+    # 
+    # @return [Array<Abachrome::Color>] A duplicate of the palette's color array
     def to_a
       @colors.dup
     end
 
+    # Access a color in the palette at the specified index.
+    # 
+    # @param index [Integer] The index of the color to retrieve from the palette
+    # @return [Abachrome::Color, nil] The color at the specified index, or nil if the index is out of bounds
     def [](index)
       @colors[index]
     end
 
+    # Slices the palette to create a new palette with a subset of colors.
+    # 
+    # @param start [Integer] The starting index (or range) from which to start the slice.
+    # @param length [Integer, nil] The number of colors to include in the slice. If nil and start is an Integer,
+    # returns a new palette containing the single color at that index. If start is a Range, length is ignored.
+    # @return [Abachrome::Palette] A new palette containing the selected colors.
     def slice(start, length = nil)
       new_colors = length ? @colors[start, length] : @colors[start]
       self.class.new(new_colors)
     end
 
+    # Returns the first color in the palette.
+    # 
+    # @return [Abachrome::Color, nil] The first color in the palette, or nil if the palette is empty.
     def first
       @colors.first
     end
 
+    # Returns the last color in the palette.
+    # 
+    # @return [Abachrome::Color, nil] The last color in the palette or nil if palette is empty.
     def last
       @colors.last
     end
 
+    # Returns a new palette with colors sorted by lightness.
+    # This method creates a new palette instance containing the same colors as the current
+    # palette but sorted in ascending order based on their lightness values.
+    # 
+    # @return [Abachrome::Palette] a new palette with the same colors sorted by lightness
     def sort_by_lightness
       self.class.new(@colors.sort_by(&:lightness))
     end
 
+    # Returns a new palette with colors sorted by saturation from lowest to highest.
+    # Saturation is determined by the second coordinate (a*) in the OKLAB color space.
+    # Lower values represent less saturated colors, higher values represent more saturated colors.
+    # 
+    # @return [Abachrome::Palette] A new palette instance with the same colors sorted by saturation
     def sort_by_saturation
       self.class.new(@colors.sort_by { |c| c.to_oklab.coordinates[1] })
     end
 
+    # Blends all colors in the palette together sequentially at the specified amount.
+    # This method takes each color in the palette and blends it with the accumulated result
+    # of previous blends. It starts with the first color and progressively blends each subsequent
+    # color at the specified blend amount.
+    # 
+    # @param amount [Float] The blend amount to use between each color pair, between 0.0 and 1.0.
+    # Defaults to 0.5 (equal blend).
+    # @return [Abachrome::Color, nil] The final blended color result, or nil if the palette is empty.
     def blend_all(amount = 0.5)
       return nil if empty?
 
@@ -84,6 +174,13 @@ module Abachrome
       result
     end
 
+    # Calculates the average color of the palette by finding the centroid in OKLAB space.
+    # This method converts each color in the palette to OKLAB coordinates,
+    # calculates the arithmetic mean of these coordinates, and creates a new
+    # color from the average values. Alpha values are also averaged.
+    # 
+    # @return [Abachrome::Color, nil] The average color of all colors in the palette,
+    # or nil if the palette is empty
     def average
       return nil if empty?
 
@@ -100,6 +197,16 @@ module Abachrome
       )
     end
 
+    # Converts the colors in the palette to CSS-formatted strings.
+    # 
+    # The format of the output can be specified with the format parameter.
+    # 
+    # @param format [Symbol] The format to use for the CSS color strings.
+    # :hex - Outputs colors in hexadecimal format (e.g., "#RRGGBB")
+    # :rgb - Outputs colors in rgb() function format
+    # :oklab - Outputs colors in oklab() function format
+    # When any other value is provided, a default format is used.
+    # @return [Array<String>] An array of CSS-formatted color strings
     def to_css(format: :hex)
       to_a.map do |color|
         case format
@@ -115,6 +222,9 @@ module Abachrome
       end
     end
 
+    # Returns a string representation of the palette for inspection purposes.
+    # 
+    # @return [String] A string containing the class name and a list of colors in the palette
     def inspect
       "#<#{self.class} colors=#{@colors.map(&:to_s)}>"
     end
@@ -128,4 +238,4 @@ module Abachrome
       include mixin_module
     end
   end
-end
+end

data/lib/abachrome/palette_mixins/interpolate.rb

@@ -1,4 +1,22 @@
-# frozen_string_literal: true
+# Abachrome::PaletteMixins::Interpolate - Color palette interpolation functionality
+#
+# This mixin provides methods for interpolating between adjacent colors in a palette to create
+# smooth color transitions and gradients. The interpolation process inserts new colors between
+# existing palette colors by blending them at calculated intervals, creating smoother color
+# progressions ideal for gradients, color ramps, and visual transitions.
+#
+# Key features:
+# - Insert specified number of interpolated colors between each adjacent color pair
+# - Both non-destructive (interpolate) and destructive (interpolate!) variants
+# - Uses color blending in the current color space for smooth transitions
+# - Maintains original colors as anchor points in the interpolated result
+# - High-precision decimal arithmetic for accurate color calculations
+# - Preserves alpha values during interpolation process
+#
+# The mixin includes both immutable methods that return new palette instances and mutable
+# methods that modify the current palette object in place, providing flexibility for
+# different use cases and performance requirements. Interpolation is essential for creating
+# smooth color gradients and ensuring adequate color resolution in palette-based applications.
 
 module Abachrome
   module PaletteMixins
@@ -28,4 +46,4 @@ module Abachrome
       end
     end
   end
-end
+end

data/lib/abachrome/palette_mixins/resample.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: true
+#
 
 module Abachrome
   module PaletteMixins
@@ -56,4 +56,4 @@ module Abachrome
       end
     end
   end
-end
+end

data/lib/abachrome/palette_mixins/stretch_luminance.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: true
+#
 
 module Abachrome
   module PaletteMixins
@@ -67,4 +67,4 @@ module Abachrome
       end
     end
   end
-end
+end

data/lib/abachrome/parsers/hex.rb

@@ -1,4 +1,4 @@
-# frozen_string_literal: true
+#
 
 module Abachrome
   module Parsers
@@ -47,4 +47,4 @@ module Abachrome
       end
     end
   end
-end
+end

data/lib/abachrome/to_abcd.rb

@@ -1,7 +1,15 @@
-# frozen_string_literal: true
+#
 
 module Abachrome
   module ToAbcd
+    # Converts the receiver to an AbcDecimal object.
+    # 
+    # This method converts the receiver (typically a numeric value) to an AbcDecimal
+    # instance, which provides high precision decimal arithmetic capabilities for
+    # color space calculations.
+    # 
+    # @return [Abachrome::AbcDecimal] a new AbcDecimal instance representing the
+    # same numeric value as the receiver
     def to_abcd
       AbcDecimal.new(self)
     end
@@ -10,4 +18,4 @@ end
 
 [Numeric, String, Rational].each do |klass|
   klass.include(Abachrome::ToAbcd)
-end
+end

data/lib/abachrome/version.rb

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

data/lib/abachrome.rb

@@ -1,4 +1,18 @@
-# frozen_string_literal: true
+# Abachrome - A Ruby color manipulation library
+#
+# This is the main entry point for the Abachrome library, providing color creation,
+# conversion, and manipulation capabilities across multiple color spaces including
+# sRGB, OKLAB, OKLCH, and linear RGB.
+#
+# Key features:
+# - Create colors from RGB, OKLAB, OKLCH values or hex strings
+# - Convert between different color spaces
+# - Parse colors from hex codes and CSS color names
+# - Register custom color spaces and converters
+# - High-precision decimal arithmetic for accurate color calculations
+#
+# The library uses autoloading for efficient memory usage and provides both
+# functional and object-oriented APIs for color operations.
 
 require_relative "abachrome/to_abcd"
 
@@ -57,27 +71,69 @@ module Abachrome
     autoload :Hex, "abachrome/parsers/hex"
   end
 
+  # Creates a new color in the specified color space with given coordinates and alpha value.
+  # 
+  # @param space_name [Symbol, String] The name of the color space (e.g., :srgb, :oklch)
+  # @param coordinates [Array<Numeric>] The color coordinates in the specified color space
+  # @param alpha [Float] The alpha (opacity) value of the color, defaults to 1.0 (fully opaque)
+  # @return [Abachrome::Color] A new Color object in the specified color space with the given coordinates
   def create_color(space_name, *coordinates, alpha: 1.0)
     space = ColorSpace.find(space_name)
     Color.new(space, coordinates, alpha)
   end
 
+  # Creates a color object from RGB values.
+  # 
+  # @param r [Numeric] The red component value (typically 0-255 or 0.0-1.0)
+  # @param g [Numeric] The green component value (typically 0-255 or 0.0-1.0)
+  # @param b [Numeric] The blue component value (typically 0-255 or 0.0-1.0)
+  # @param alpha [Float] The alpha (opacity) component value (0.0-1.0), defaults to 1.0 (fully opaque)
+  # @return [Abachrome::Color] A new Color object initialized with the specified RGB values
   def from_rgb(r, g, b, alpha = 1.0)
     Color.from_rgb(r, g, b, alpha)
   end
 
+  # Creates a color in the OKLAB color space.
+  # 
+  # @param l [Numeric] The lightness component (L) in the OKLAB color space, typically in range 0 to 1
+  # @param a [Numeric] The green-red component (a) in the OKLAB color space
+  # @param b [Numeric] The blue-yellow component (b) in the OKLAB color space
+  # @param alpha [Float] The alpha (opacity) value, ranging from 0.0 (transparent) to 1.0 (opaque), defaults to 1.0
+  # @return [Abachrome::Color] A new Color object in the OKLAB color space
   def from_oklab(l, a, b, alpha = 1.0)
     Color.from_oklab(l, a, b, alpha)
   end
 
+  # Creates a new color from OKLCH color space values.
+  # 
+  # @param l [Numeric] The lightness value, typically in range 0-1
+  # @param a [Numeric] The chroma (colorfulness) value
+  # @param b [Numeric] The hue angle value in degrees (0-360)
+  # @param alpha [Numeric] The alpha (opacity) value, between 0-1 (default: 1.0)
+  # @return [Abachrome::Color] A new color object initialized with the given OKLCH values
   def from_oklch(l, a, b, alpha = 1.0)
     Color.from_oklch(l, a, b, alpha)
   end
 
+  # Creates a color object from a hexadecimal color code string.
+  # 
+  # @param hex_str [String] The hexadecimal color code string to parse. Can be in formats like
+  # "#RGB", "#RRGGBB", "RGB", or "RRGGBB", with or without the leading "#" character.
+  # @return [Abachrome::Color] A new Color object representing the parsed hexadecimal color.
+  # @example
+  # Abachrome.from_hex("#ff0000") # => returns a red Color object
+  # Abachrome.from_hex("00ff00")  # => returns a green Color object
+  # @see Abachrome::Parsers::Hex.parse
   def from_hex(hex_str)
     Parsers::Hex.parse(hex_str)
   end
 
+  # Creates a color object from a CSS color name.
+  # 
+  # @param color_name [String] The CSS color name (e.g., 'red', 'blue', 'cornflowerblue').
+  # Case-insensitive.
+  # @return [Abachrome::Color, nil] A color object in the RGB color space if the name is valid,
+  # nil if the color name is not recognized.
   def from_name(color_name)
     rgb_values = Named::CSS::ColorNames[color_name.downcase]
     return nil unless rgb_values
@@ -85,15 +141,35 @@ module Abachrome
     from_rgb(*rgb_values.map { |v| v / 255.0 })
   end
 
+  # Convert a color from its current color space to another color space.
+  # 
+  # @param color [Abachrome::Color] The color object to convert
+  # @param to_space [Symbol, String] The destination color space identifier (e.g. :srgb, :oklch)
+  # @return [Abachrome::Color] A new color object in the specified color space
   def convert(color, to_space)
     Converter.convert(color, to_space)
   end
 
+  # Register a new color space with the Abachrome library.
+  # 
+  # @param name [Symbol, String] The identifier for the color space being registered
+  # @param block [Proc] A block that defines the color space properties and conversion rules
+  # @return [Abachrome::ColorSpace] The newly registered color space object
   def register_color_space(name, &block)
     ColorSpace.register(name, &block)
   end
 
+  # Register a new color space converter in the Abachrome system.
+  # 
+  # This method allows registering custom converters between color spaces.
+  # Converters are used to transform color representations from one color
+  # space to another.
+  # 
+  # @param from_space [Symbol, String] The source color space identifier
+  # @param to_space [Symbol, String] The destination color space identifier
+  # @param converter [#call] An object responding to #call that performs the conversion
+  # @return [void]
   def register_converter(from_space, to_space, converter)
     Converter.register(from_space, to_space, converter)
   end
-end
+end

metadata

@@ -1,96 +1,44 @@
 --- !ruby/object:Gem::Specification
 name: abachrome
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
-- Durable Programming, LLC
+- Durable Programming
 autorequire:
 bindir: exe
 cert_chain: []
 date: 1980-01-01 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: bigdecimal
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 3.0.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 3.0.0
 - !ruby/object:Gem::Dependency
   name: dry-inflector
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.2.0
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.2.0
-- !ruby/object:Gem::Dependency
-  name: minitest
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 5.25.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 5.25.0
-- !ruby/object:Gem::Dependency
-  name: rake
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '13.0'
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.22.0
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 0.22.0
-description: 'Abachrome provides a robust set of tools for working with colors: parsing,
-  manipulation, conversion, etc. Supports RGB, HSV, OkLab and OkLch.'
+        version: '1.0'
+description: Abachrome provides a robust set of tools for working with various color
+  formats including hex, RGB, HSL, and named colors. Features support for multiple
+  color spaces (RGB, HSL, Lab, Oklab), color space conversion, gamut mapping, CSS
+  color parsing and formatting, and high-precision color calculations using BigDecimal.
 email:
-- info@durableprogramming.com
+- commercial@durableprogramming.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".envrc"
 - ".rubocop.yml"
 - CHANGELOG.md
 - README.md
+- Rakefile
 - demos/ncurses/plasma.rb
 - devenv.lock
 - devenv.nix
@@ -141,15 +89,15 @@ files:
 - lib/abachrome/parsers/hex.rb
 - lib/abachrome/to_abcd.rb
 - lib/abachrome/version.rb
+- logo.png
+- logo.webp
 homepage: https://github.com/durableprogramming/abachrome
 licenses:
 - MIT
 metadata:
-  allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/durableprogramming/abachrome
   source_code_uri: https://github.com/durableprogramming/abachrome
   changelog_uri: https://github.com/durableprogramming/abachrome/blob/main/CHANGELOG.md
-  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
@@ -165,8 +113,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.22
+rubygems_version: 3.5.9
 signing_key:
 specification_version: 4
-summary: Color parsing, manipulation, and formatting tools.
+summary: A Ruby gem for parsing, manipulating, and managing colors
 test_files: []