kodachroma 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 98d99d23181a6e8fb5b66b9cc689fff97881ab9cc9bf2ae455da8b85c915f6bb
+  data.tar.gz: 05f09a107f88e5938173309b7a84d81b8930940419729cd152e97c11fb5b093f
+SHA512:
+  metadata.gz: 88ab6243470b9a773de8b37f12b067863cdf7cc0aa48f47e85b69f928280ab9a2394709ae28286ffd9eeb6b262407c75c724faeca4ffb6cf27efc0aa2927f1d1
+  data.tar.gz: 4df903a5512b146f9da7f564db65b5f5d441bb891a664734701027a437eda3cd3b1efbaf8e86e2deb97805935e7c04c22ad49c59c7ab36ed20a2092473119fff

data/LICENSE.txt

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright © 2021 Jeremy Fairbank and Evan Lecklider
+
+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.org

@@ -0,0 +1,401 @@
+* Kodachroma
+
+[[https://badge.fury.io/rb/kodachroma][https://badge.fury.io/rb/kodachroma.svg]]
+
+Kodachroma is a color manipulation and palette generation library. It aims to be
+a maintained fork of the excellent [[https://github.com/jfairbank/chroma][Chroma]]. Many thanks to [[https://github.com/jfairbank][Jeremy Fairbank]] for
+developing Chroma.
+
+From Chroma's own [[https://github.com/jfairbank/chroma/blob/master/README.md][README]]:
+
+#+begin_quote
+It is heavily inspired by and a very close Ruby port of the [[https://bgrins.github.io/TinyColor/][tinycolor.js]]
+library. Many thanks to [[http://www.briangrinstead.com/blog/][Brian Grinstead]] for his hard work on that library.
+#+end_quote
+
+** Installation
+
+Add this line to your application's Gemfile:
+
+#+BEGIN_SRC ruby
+gem 'kodachroma'
+#+END_SRC
+
+And then execute:
+
+#+begin_src sh
+bundle
+#+end_src
+
+Or install it yourself as:
+
+#+begin_src sh
+gem install kodachroma
+#+end_src
+
+** Differences from Chroma
+
+The string extension that defined =String#paint= has been removed. If you would
+like to replicate that behavior using Kodachroma, the following should do the
+trick.
+
+#+begin_src ruby
+class String
+  # Creates {Kodachroma::Color} directly from a string representing a color.
+  #
+  # @example
+  #   'red'.paint
+  #   '#f00'.paint
+  #   '#ff0000'.paint
+  #   'rgb(255, 0, 0)'.paint
+  #   'hsl(0, 100%, 50%)'.paint
+  #   'hsv(0, 100%, 100%)'.paint
+  #
+  # @return [Kodachroma::Color]
+  def paint
+    Kodachroma.paint(self)
+  end
+end
+#+end_src
+
+** Creating Colors
+
+Colors are created via the =Kodachroma.paint= method. It expects any one of
+many possible color formats as a string, including names, hexadecimal,
+rgb, hsl, and hsv.
+
+#+BEGIN_SRC ruby
+Kodachroma.paint 'red'                       # named colors
+Kodachroma.paint '#00ff00'                   # 6 character hexadecimal
+Kodachroma.paint '#00f'                      # 3 character hexadecimal
+Kodachroma.paint 'rgb(255, 255, 0)'          # rgb
+Kodachroma.paint 'rgba(255, 255, 0, 0.5)'    # rgba
+Kodachroma.paint 'hsl(60, 100%, 50%)'        # hsl with percentages
+Kodachroma.paint 'hsl(60, 1, 0.5)'           # hsl with decimals
+Kodachroma.paint 'hsla(60, 100%, 50%, 0.5)'  # hsla
+Kodachroma.paint 'hsv(60, 100%, 50%)'        # hsv with percentages
+Kodachroma.paint 'hsv(60, 1, 0.5)'           # hsv with decimals
+Kodachroma.paint 'hsva(60, 100%, 50%, 0.75)' # hsva
+#+END_SRC
+
+** Motivation
+
+Kodachroma's major strength is manipulating colors and generating color
+palettes, which allows you to easily generate dynamic colors, dynamic
+themes for a web application, and more.
+
+** Color manipulation
+
+*** Lighten
+
+Lighten the color by a given amount. Defaults to 10.
+
+#+BEGIN_SRC ruby
+Kodachroma.paint('red').lighten     #=> #ff3333
+Kodachroma.paint('red').lighten(20) #=> #ff6666
+#+END_SRC
+
+*** Brighten
+
+Brighten the color by a given amount. Defaults to 10.
+
+#+BEGIN_SRC ruby
+Kodachroma.paint('red').brighten     #=> #ff1a1a
+Kodachroma.paint('red').brighten(20) #=> #ff3333
+#+END_SRC
+
+*** Darken
+
+Darken the color by a given amount. Defaults to 10.
+
+#+BEGIN_SRC ruby
+Kodachroma.paint('red').darken     #=> #cc0000
+Kodachroma.paint('red').darken(20) #=> #990000
+#+END_SRC
+
+*** Desaturate
+
+Desaturate the color by a given amount. Defaults to 10.
+
+#+BEGIN_SRC ruby
+Kodachroma.paint('red').desaturate     #=> #f20d0d
+Kodachroma.paint('red').desaturate(20) #=> #e61919
+#+END_SRC
+
+*** Saturate
+
+Saturate the color by a given amount. Defaults to 10.
+
+#+BEGIN_SRC ruby
+Kodachroma.paint('#123').saturate     #=> #0e2236
+Kodachroma.paint('#123').saturate(20) #=> #0a223a
+#+END_SRC
+
+*** Grayscale
+
+Convert the color to grayscale.
+
+#+BEGIN_SRC ruby
+Kodachroma.paint('green').grayscale #=> #404040
+
+# greyscale is an alias
+Kodachroma.paint('red').greyscale   #=> #808080
+#+END_SRC
+
+*** Opacity
+
+Set the opacity of the color to a given amount.
+
+#+BEGIN_SRC ruby
+Kodachroma.paint('red').opacity(0.3) #=> #ff0000
+Kodachroma.paint('red').opacity(0.3).to_rgb #=> 'rgba(255, 0, 0, 0.3)'
+#+END_SRC
+
+*** Spin
+
+Spin a given amount in degrees around the hue wheel.
+
+#+BEGIN_SRC ruby
+Kodachroma.paint('red').spin(30) #=> #ff8000
+Kodachroma.paint('red').spin(60) #=> yellow
+Kodachroma.paint('red').spin(90) #=> #80ff00
+#+END_SRC
+
+** Generating palettes
+
+Kodachroma's most powerful feature is palette generation. You can use the
+default palettes available or even create your own custom palettes.
+
+Palette methods are available via =Color#palette= and by default output
+an array of colors. If you want the underlying color strings, you can
+pass in the desired format via the =:as= option.
+
+**** Available Formats
+
+- name
+- rgb
+- hex
+- hex6 (alias for hex)
+- hex3
+- hex8 (includes the alpha value in the highest order byte)
+- hsl
+- hsv
+
+**** Complement
+
+Generate a complement palette.
+
+#+BEGIN_SRC ruby
+Kodachroma.paint('red').palette.complement            #=> [red, cyan]
+Kodachroma.paint('red').palette.complement(as: :name) #=> ['red', 'cyan']
+Kodachroma.paint('red').palette.complement(as: :hex)  #=> ['#ff0000', '#00ffff']
+#+END_SRC
+
+**** Triad
+
+Generate a triad palette.
+
+#+BEGIN_SRC ruby
+Kodachroma.paint('red').palette.triad            #=> [red, lime, blue]
+Kodachroma.paint('red').palette.triad(as: :name) #=> ['red', 'lime', 'blue']
+Kodachroma.paint('red').palette.triad(as: :hex)  #=> ['#ff0000', '#00ff00', '#0000ff']
+#+END_SRC
+
+**** Tetrad
+
+Generate a tetrad palette.
+
+#+BEGIN_SRC ruby
+Kodachroma.paint('red').palette.tetrad
+#=> [red, #80ff00, cyan, #7f00ff]
+
+Kodachroma.paint('red').palette.tetrad(as: :name)
+#=> ['red', '#80ff00', 'cyan', '#7f00ff']
+
+Kodachroma.paint('red').palette.tetrad(as: :hex)
+#=> ['#ff0000', '#80ff00', '#00ffff', '#7f00ff']
+#+END_SRC
+
+**** Split complement
+
+Generate a split complement palette.
+
+#+BEGIN_SRC ruby
+Kodachroma.paint('red').palette.split_complement
+#=> [red, #ccff00, #0066ff]
+
+Kodachroma.paint('red').palette.split_complement(as: :name)
+#=> ['red', '#ccff00', '#0066ff']
+
+Kodachroma.paint('red').palette.split_complement(as: :hex)
+#=> ['#ff0000', '#ccff00', '#0066ff']
+#+END_SRC
+
+**** Analogous
+
+Generate an analogous palette. Pass in a =:size= option to specify the
+size of the palette (defaults to 6). Pass in a =:slice_by= option to
+specify the angle size to slice into the hue wheel (defaults to 30
+degrees).
+
+#+BEGIN_SRC ruby
+Kodachroma.paint('red').palette.analogous
+#=> [red, #ff0066, #ff0033, red, #ff3300, #ff6600]
+
+Kodachroma.paint('red').palette.analogous(as: :hex)
+#=> ['#f00', '#f06', '#f03', '#f00', '#f30', '#f60']
+
+Kodachroma.paint('red').palette.analogous(size: 3)
+#=> [red, #ff001a, #ff1a00]
+
+Kodachroma.paint('red').palette.analogous(size: 3, slice_by: 60)
+#=> [red, #ff000d, #ff0d00]
+#+END_SRC
+
+**** Monochromatic
+
+Generate a monochromatic palette. Pass in a =:size= option to specify
+the size of the palette (defaults to 6).
+
+#+BEGIN_SRC ruby
+Kodachroma.paint('red').palette.monochromatic
+#=> [red, #2a0000, #550000, maroon, #aa0000, #d40000]
+
+Kodachroma.paint('red').palette.monochromatic(as: :hex)
+#=> ['#ff0000', '#2a0000', '#550000', '#800000', '#aa0000', '#d40000']
+
+Kodachroma.paint('red').palette.monochromatic(size: 3)
+#=> [red, #550000, #aa0000]
+#+END_SRC
+
+** Defining custom palettes
+
+Kodachroma allows you to define your own custom palettes if the default ones
+aren't all you're looking for. You can define a custom palette by
+calling =Kodachroma.define_palette=, passing in a palette name and
+definition block. The definition block uses the color manipulation
+methods (i.e. =lighten=, =spin=, etc.) as its DSL. Every DSL call
+defines a new color that will be included in the palette. Your seed
+color (i.e. the color from which you call the palette method) will be
+included as the first color in your palette too.
+
+#+BEGIN_SRC ruby
+red = Kodachroma.paint('red')
+
+red.palette.respond_to? :my_palette #=> false
+
+# Define a palette with 5 colors including the seed color
+Kodachroma.define_palette :my_palette do
+  spin 60
+  spin 180
+  spin(60).brighten(20) # chain calls as well
+  greyscale
+end
+
+red.palette.respond_to? :my_palette #=> true
+
+red.palette.my_palette #=> [#ff0000 #ffff00 #00ffff #ffff33 #808080]
+#+END_SRC
+
+** Dynamic custom palettes
+
+You can generate custom palettes on the fly too with
+=Kodachroma::Color#custom_palette=.
+
+#+BEGIN_SRC ruby
+Kodachroma.paint('red').custom_palette do
+  spin 60
+  spin 180
+end
+
+#=> [red, yellow, cyan]
+#+END_SRC
+
+** Serializing colors
+
+Colors offer several methods to output to different string color
+[[#available-formats][formats]].
+
+| Method      | Description                                                                                                        |
+|-------------+--------------------------------------------------------------------------------------------------------------------|
+| =to_hsv=    | output to hsv string, outputs hsva if alpha < 1                                                                    |
+| =to_hsl=    | output to hsl string, outputs hsla if alpha < 1                                                                    |
+| =to_hex=    | output to hex string, optional argument allows 3-character hex output if possible                                  |
+| =to_hex8=   | output to 8-character hex string with alpha value in the highest order byte                                        |
+| =to_rgb=    | output to rgb string, outputs rgba if alpha < 1                                                                    |
+| =to_name=   | output to color name string if available, otherwise ='<unknown>'= or =to_hex= output based on optional arg value   |
+| =to_s=      | output to the appropriate string format based on how the color was created, optional arg forces the format         |
+
+#+BEGIN_SRC ruby
+# to_hsv
+Kodachroma.paint('red').to_hsv                  #=> 'hsv(0, 100%, 100%)'
+Kodachroma.paint('rgba(255, 0, 0, 0.5)').to_hsv #=> 'hsva(0, 100%, 100%, 0.5)'
+
+# to_hsl
+Kodachroma.paint('red').to_hsl                  #=> 'hsl(0, 100%, 50%)'
+Kodachroma.paint('rgba(255, 0, 0, 0.5)').to_hsl #=> 'hsla(0, 100%, 50%, 0.5)'
+
+# to_hex
+Kodachroma.paint('red').to_hex                  #=> '#ff0000'
+Kodachroma.paint('red').to_hex(true)            #=> '#f00'
+Kodachroma.paint('rgba(255, 0, 0, 0.5)').to_hex #=> '#ff0000'
+Kodachroma.paint('red').to_hex                  #=> '#ffff0000'
+Kodachroma.paint('rgba(255, 0, 0, 0.5)').to_hex #=> '#80ff0000'
+
+# to_rgb
+Kodachroma.paint('red').to_rgb                  #=> 'rgb(255, 0, 0)'
+Kodachroma.paint('rgba(255, 0, 0, 0.5)').to_rgb #=> 'rgb(255, 0, 0, 0.5)'
+
+# to_name
+Kodachroma.paint('red').to_name                  #=> 'red'
+Kodachroma.paint('#00f').to_name                 #=> 'blue'
+Kodachroma.paint('rgba(255, 0, 0, 0.5)').to_name #=> '<unknown>'
+Kodachroma.paint('#123').to_name(true)           #=> '#112233'
+
+# to_s
+Kodachroma.paint('red').to_s             #=> 'red'
+Kodachroma.paint('rgb(255, 0, 0)').to_s  #=> 'rgb(255, 0, 0)'
+Kodachroma.paint('#f00').to_s            #=> '#f00'
+Kodachroma.paint('#80ff0000').to_s(:rgb) #=> 'rgba(255, 0, 0, 0.5)'
+#+END_SRC
+
+** Other methods
+
+Colors also have a few other helper methods:
+
+| Method         | Description                                              |
+|----------------+----------------------------------------------------------|
+| =dark?=        | is the color dark?                                       |
+| =light?=       | is the color light?                                      |
+| =alpha=        | retrieve the alpha value                                 |
+| =brightness=   | calculate the brightness as a number between 0 and 255   |
+| =complement=   | return the complementary color                           |
+
+#+BEGIN_SRC ruby
+# dark?
+Kodachroma.paint('red').dark?    #=> true
+Kodachroma.paint('yellow').dark? #=> false
+
+# light?
+Kodachroma.paint('red').light?    #=> false
+Kodachroma.paint('yellow').light? #=> true
+
+# alpha
+Kodachroma.paint('red').alpha                #=> 1.0
+Kodachroma.paint('rgba(0, 0, 0, 0.5)').alpha #=> 0.5
+
+# brightness
+Kodachroma.paint('red').brightness    #=> 76.245
+Kodachroma.paint('yellow').brightness #=> 225.93
+Kodachroma.paint('white').brightness  #=> 255.0
+Kodachroma.paint('black').brightness  #=> 0.0
+
+# complement
+Kodachroma.paint('red').complement #=> cyan
+#+END_SRC
+
+** Trivia
+
+The name "Kodachroma" is inspired by Paul Simon's lovely song "Kodachrome" and
+my desire to keep "chroma" in the name of the gem so people searching for the
+original gem might find this fork.

data/lib/kodachroma/color/attributes.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+module Kodachroma
+  class Color
+    # Attribute methods for {Color}.
+    module Attributes
+      attr_reader :format
+
+      # Determines if the color is dark.
+      #
+      # @example
+      #   'red'.paint.dark?    #=> true
+      #   'yellow'.paint.dark? #=> false
+      #
+      # @return [true, false]
+      def dark?
+        brightness < 128
+      end
+
+      # Determines if the color is light.
+      #
+      # @example
+      #   'red'.paint.light?    #=> false
+      #   'yellow'.paint.light? #=> true
+      #
+      # @return [true, false]
+      def light?
+        !dark?
+      end
+
+      # Returns the alpha channel value.
+      #
+      # @example
+      #   'red'.paint.alpha                #=> 1.0
+      #   'rgba(0, 0, 0, 0.5)'.paint.alpha #=> 0.5
+      #
+      # @return [Float]
+      def alpha
+        @rgb.a
+      end
+
+      # Calculates the brightness.
+      #
+      # @example
+      #   'red'.paint.brightness    #=> 76.245
+      #   'yellow'.paint.brightness #=> 225.93
+      #
+      # @return [Float]
+      def brightness
+        ((@rgb.r * 299) + (@rgb.g * 587) + (@rgb.b * 114)) / 1000.0
+      end
+
+      private
+
+      def rounded_alpha
+        @rounded_alpha ||= (alpha * 100).round / 100.0
+      end
+    end
+  end
+end