unmagic-color 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c7be12ac8d10a2afce0fb4b18e79bd8636f7000e154a6cd55254ef0284498ca4
+  data.tar.gz: 55be4881e50f7adad3adcd12dcb85d03c2a35bea2a26cfe6c1db16a0fe567d68
+SHA512:
+  metadata.gz: 9ffad3c4830a9d79c9603fde9a59fcab9714a5cbc7fa91fa2857b2665cea5f3796b7842f89627c24765d9996fd28a80562f4756f7392764ad620f512e3b4d543
+  data.tar.gz: dbdfb73585f752f60089658c273b65a69a2189746f8379133db427038af006667589f199e6fd00eeeb6a8dda47142fd5f4aa9c25f1279d1f00864309fbfc0903

data/README.md

@@ -0,0 +1,274 @@
+# Unmagic Color
+
+A comprehensive Ruby color manipulation library with support for RGB, HSL, and OKLCH color spaces. Parse, convert, and manipulate colors with an intuitive API.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'unmagic-color'
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install unmagic-color
+```
+
+## Features
+
+- **Multiple Color Spaces**: RGB, HSL, and OKLCH support
+- **Flexible Parsing**: Parse colors from hex, CSS format strings, named colors, or component values
+- **Named Colors**: Support for [X11 color names](https://en.wikipedia.org/wiki/X11_color_names) (red, blue, goldenrod, etc.)
+- **Color Conversions**: Seamlessly convert between color spaces
+- **Color Manipulation**: Lighten, darken, and blend colors
+- **Deterministic Generation**: Generate consistent colors from strings or seeds
+- **Luminance Calculation**: Determine if colors are light or dark
+- **Color Progressions**: Create color scales and palettes
+
+## Quick Start
+
+```ruby
+require 'unmagic/color'
+
+# Parse a color
+color = Unmagic::Color.parse("#FF5733")
+
+# Convert to different color spaces
+hsl = color.to_hsl
+oklch = color.to_oklch
+
+# Manipulate colors
+lighter = color.lighten(0.2)
+darker = color.darken(0.1)
+
+# Check luminance
+color.light?  # => false
+color.dark?   # => true
+```
+
+## Usage Examples
+
+### Parsing Colors
+
+```ruby
+# From hex
+color = Unmagic::Color.parse("#FF5733")
+color = Unmagic::Color["#F57"]  # Short form
+
+# From RGB
+color = Unmagic::Color.parse("rgb(255, 87, 51)")
+color = Unmagic::Color::RGB.new(red: 255, green: 87, blue: 51)
+
+# From HSL
+color = Unmagic::Color.parse("hsl(9, 100%, 60%)")
+color = Unmagic::Color::HSL.new(hue: 9, saturation: 100, lightness: 60)
+
+# From OKLCH
+color = Unmagic::Color.parse("oklch(0.65 0.15 30)")
+color = Unmagic::Color::OKLCH.new(lightness: 0.65, chroma: 0.15, hue: 30)
+
+# From X11 named colors (https://en.wikipedia.org/wiki/X11_color_names)
+color = Unmagic::Color.parse("goldenrod")
+color = Unmagic::Color["red"]
+
+# Named colors are case-insensitive and whitespace-tolerant
+color = Unmagic::Color.parse("Golden Rod")  # Same as "goldenrod"
+color = Unmagic::Color.parse("DARK SLATE BLUE")  # Same as "darkslateblue"
+```
+
+### Converting Between Color Spaces
+
+```ruby
+rgb = Unmagic::Color.parse("#FF5733")
+
+# Convert to HSL
+hsl = rgb.to_hsl
+puts hsl.hue.to_f        # => 9.0
+puts hsl.saturation.to_f # => 100.0
+puts hsl.lightness.to_f  # => 60.0
+
+# Convert to OKLCH
+oklch = rgb.to_oklch
+
+# Convert back to hex
+hex = hsl.to_rgb.to_hex
+puts hex  # => "#FF5733"
+```
+
+### Color Manipulation
+
+```ruby
+color = Unmagic::Color.parse("#336699")
+
+# Make it lighter or darker
+lighter = color.lighten(0.2)  # 20% lighter
+darker = color.darken(0.1)    # 10% darker
+
+# Blend two colors
+red = Unmagic::Color.parse("#FF0000")
+blue = Unmagic::Color.parse("#0000FF")
+purple = red.blend(blue, 0.5)  # 50/50 mix
+
+# Check if color is light or dark
+if color.light?
+  text_color = "#000000"  # Use dark text
+else
+  text_color = "#FFFFFF"  # Use light text
+end
+```
+
+### HSL-Specific Features
+
+```ruby
+hsl = Unmagic::Color::HSL.new(hue: 200, saturation: 70, lightness: 50)
+
+# Adjust individual components
+brighter = hsl.lighten(0.15)
+muted = hsl.desaturate(0.3)
+shifted = hsl.adjust_hue(30)
+
+# Create color progressions
+palette = hsl.progression(
+  steps: 5,
+  lightness: [30, 50, 70, 85, 95]
+)
+# => Array of 5 HSL colors with varying lightness
+```
+
+### Generating Colors from Strings
+
+Generate consistent, deterministic colors from any string:
+
+```ruby
+# Generate from a user ID or name
+color = Unmagic::Color::RGB.derive("user_12345".hash)
+color = Unmagic::Color::HSL.derive("john.doe@example.com".hash)
+
+# Customize the output
+color = Unmagic::Color::RGB.derive(
+  "project_alpha".hash,
+  brightness: 200,    # Brighter colors
+  saturation: 0.8     # More saturated
+)
+
+color = Unmagic::Color::HSL.derive(
+  "team_rocket".hash,
+  lightness: 60,              # Target lightness
+  saturation_range: (50..70)  # Saturation range
+)
+```
+
+### Advanced: Hash Functions for Color Generation
+
+For more control over how strings map to colors, use hash functions:
+
+```ruby
+# Use different hash algorithms
+hash_value = Unmagic::Color::String::HashFunction::DJB2.call("username")
+color = Unmagic::Color::RGB.derive(hash_value)
+
+# Color-aware hashing (biases toward color names in string)
+hash_value = Unmagic::Color::String::HashFunction::COLOR_AWARE.call("red_team")
+# Will produce a reddish color
+
+# Available hash functions:
+# - SUM: Simple, anagrams get same color
+# - DJB2: Good general-purpose distribution
+# - BKDR: Excellent distribution (default)
+# - FNV1A: Maximum variety for sequential strings
+# - SDBM: Good for database IDs
+# - JAVA: Compatible with Java's hashCode
+# - CRC32: Most uniform distribution
+# - MD5: Cryptographic hash (slower)
+# - POSITION: Order-sensitive
+# - PERCEPTUAL: Case-insensitive
+# - COLOR_AWARE: Detects color names
+# - MURMUR3: Fast with excellent distribution
+```
+
+### Working with Color Components
+
+```ruby
+rgb = Unmagic::Color::RGB.new(red: 255, green: 87, blue: 51)
+
+# Access components
+puts rgb.red.to_i    # => 255
+puts rgb.green.to_i  # => 87
+puts rgb.blue.to_i   # => 51
+
+hsl = Unmagic::Color::HSL.new(hue: 180, saturation: 50, lightness: 60)
+
+# Access components
+puts hsl.hue.to_f         # => 180.0
+puts hsl.saturation.to_f  # => 50.0
+puts hsl.lightness.to_f   # => 60.0
+
+# Components support arithmetic
+new_hue = hsl.hue + 30  # Shift hue by 30 degrees
+```
+
+### Luminance and Contrast
+
+```ruby
+color = Unmagic::Color.parse("#336699")
+
+# Get luminance (0.0 = black, 1.0 = white)
+lum = color.luminance  # => ~0.2
+
+# Check if light or dark
+color.light?  # => false
+color.dark?   # => true
+
+# Choose contrasting text color
+text_color = color.light? ? "#000000" : "#FFFFFF"
+```
+
+## Color Spaces
+
+### RGB (Red, Green, Blue)
+Standard color space for displays. Values range from 0-255 for each component.
+
+```ruby
+Unmagic::Color::RGB.new(red: 255, green: 87, blue: 51)
+```
+
+### HSL (Hue, Saturation, Lightness)
+Intuitive color space for human-friendly color manipulation.
+- Hue: 0-360 degrees (color wheel position)
+- Saturation: 0-100% (color intensity)
+- Lightness: 0-100% (brightness)
+
+```ruby
+Unmagic::Color::HSL.new(hue: 180, saturation: 70, lightness: 50)
+```
+
+### OKLCH (Lightness, Chroma, Hue)
+Perceptually uniform color space that better matches human color perception.
+
+```ruby
+Unmagic::Color::OKLCH.new(lightness: 0.65, chroma: 0.15, hue: 180)
+```
+
+## Requirements
+
+- Ruby >= 3.0
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rspec` to run the tests.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/unreasonable-magic/unmagic-color.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/data/rgb.txt

@@ -0,0 +1,164 @@
+black	#000000	
+silver	#c0c0c0	
+gray	#808080	
+white	#ffffff	
+maroon	#800000	
+red	#ff0000	
+purple	#800080	
+fuchsia	#ff00ff	
+green	#008000	
+lime	#00ff00	
+olive	#808000	
+yellow	#ffff00	
+navy	#000080	
+blue	#0000ff	
+teal	#008080	
+aqua	#00ffff
+aliceblue	#f0f8ff	
+antiquewhite	#faebd7	
+aqua	#00ffff	
+aquamarine	#7fffd4	
+azure	#f0ffff	
+beige	#f5f5dc	
+bisque	#ffe4c4	
+black	#000000	
+blanchedalmond	#ffebcd	
+blue	#0000ff	
+blueviolet	#8a2be2	
+brown	#a52a2a	
+burlywood	#deb887	
+cadetblue	#5f9ea0	
+chartreuse	#7fff00	
+chocolate	#d2691e	
+coral	#ff7f50	
+cornflowerblue	#6495ed	
+cornsilk	#fff8dc	
+crimson	#dc143c	
+cyan	##00ffff
+darkblue	#00008b	
+darkcyan	#008b8b	
+darkgoldenrod	#b8860b	
+darkgray	#a9a9a9	
+darkgreen	#006400	
+darkgrey	#a9a9a9	
+darkkhaki	#bdb76b	
+darkmagenta	#8b008b	
+darkolivegreen	#556b2f	
+darkorange	#ff8c00	
+darkorchid	#9932cc	
+darkred	#8b0000	
+darksalmon	#e9967a	
+darkseagreen	#8fbc8f	
+darkslateblue	#483d8b	
+darkslategray	#2f4f4f	
+darkslategrey	#2f4f4f	
+darkturquoise	#00ced1	
+darkviolet	#9400d3	
+deeppink	#ff1493	
+deepskyblue	#00bfff	
+dimgray	#696969	
+dimgrey	#696969	
+dodgerblue	#1e90ff	
+firebrick	#b22222	
+floralwhite	#fffaf0	
+forestgreen	#228b22	
+fuchsia	#ff00ff	
+gainsboro	#dcdcdc	
+ghostwhite	#f8f8ff	
+gold	#ffd700	
+goldenrod	#daa520	
+gray	#808080	
+green	#008000	
+greenyellow	#adff2f	
+grey	#808080
+honeydew	#f0fff0	
+hotpink	#ff69b4	
+indianred	#cd5c5c	
+indigo	#4b0082	
+ivory	#fffff0	
+khaki	#f0e68c	
+lavender	#e6e6fa	
+lavenderblush	#fff0f5	
+lawngreen	#7cfc00	
+lemonchiffon	#fffacd	
+lightblue	#add8e6	
+lightcoral	#f08080	
+lightcyan	#e0ffff	
+lightgoldenrodyellow	#fafad2	
+lightgray	#d3d3d3	
+lightgreen	#90ee90	
+lightgrey	#d3d3d3	
+lightpink	#ffb6c1	
+lightsalmon	#ffa07a	
+lightseagreen	#20b2aa	
+lightskyblue	#87cefa	
+lightslategray	#778899	
+lightslategrey	#778899	
+lightsteelblue	#b0c4de	
+lightyellow	#ffffe0	
+lime	#00ff00	
+limegreen	#32cd32	
+linen	#faf0e6	
+magenta	#ff00ff
+maroon	#800000	
+mediumaquamarine	#66cdaa	
+mediumblue	#0000cd	
+mediumorchid	#ba55d3	
+mediumpurple	#9370db	
+mediumseagreen	#3cb371	
+mediumslateblue	#7b68ee	
+mediumspringgreen	#00fa9a	
+mediumturquoise	#48d1cc	
+mediumvioletred	#c71585	
+midnightblue	#191970	
+mintcream	#f5fffa	
+mistyrose	#ffe4e1	
+moccasin	#ffe4b5	
+navajowhite	#ffdead	
+navy	#000080	
+oldlace	#fdf5e6	
+olive	#808000	
+olivedrab	#6b8e23	
+orange	#ffa500	
+orangered	#ff4500	
+orchid	#da70d6	
+palegoldenrod	#eee8aa	
+palegreen	#98fb98	
+paleturquoise	#afeeee	
+palevioletred	#db7093	
+papayawhip	#ffefd5	
+peachpuff	#ffdab9	
+peru	#cd853f	
+pink	#ffc0cb	
+plum	#dda0dd	
+powderblue	#b0e0e6	
+purple	#800080	
+rebeccapurple	#663399	
+red	#ff0000	
+rosybrown	#bc8f8f	
+royalblue	#4169e1	
+saddlebrown	#8b4513	
+salmon	#fa8072	
+sandybrown	#f4a460	
+seagreen	#2e8b57	
+seashell	#fff5ee	
+sienna	#a0522d	
+silver	#c0c0c0	
+skyblue	#87ceeb	
+slateblue	#6a5acd	
+slategray	#708090	
+slategrey	#708090	
+snow	#fffafa	
+springgreen	#00ff7f	
+steelblue	#4682b4	
+tan	#d2b48c	
+teal	#008080	
+thistle	#d8bfd8	
+tomato	#ff6347	
+turquoise	#40e0d0	
+violet	#ee82ee	
+wheat	#f5deb3	
+white	#ffffff	
+whitesmoke	#f5f5f5	
+yellow	#ffff00	
+yellowgreen	#9acd32