type: utility

release: 2.0

priority: medium

status: in development

documentation: http://oksoclap.com/jquery-color-api

demo: N/A

1 - Description:

A common set of functions for color storage and manipulation that should be utilitised by UI widgets wherever required. Also for use independently of the UI core.

Color object to parse color strings such as #rrggbb, "red",  "rgb(255,0,0)" and explicit color values as arguments/array/named-object into a color object. Every color object has transform functions to adjust/assign color values as well as transform between one color and another at a given percentage of blend.

v2.0 of jquery-color is the new jQuery.Color function object, similar to jQuery itself (creates a new object with prototype methods)

v2.1 of jquery-color will implement hsla support. 

2 - Visual Design:

N/A

3 - Functional Specifications/Requirements:

MILESTONE 1: Basic Functionality / animation

Status: Needs Review

Branch: https://github.com/jquery/jquery-color/

The $.Color function object:

• Returns a new Color object, similar to $() or $.Event
• Accepts the color value to create the new Color object with, and assigns $.Color.fn as it's prototype
• $.Color( { red: red, green: green, blue: blue, alpha: alpha } )
• $.Color( [ red, green, blue, alpha ] ) 
• $.Color( "#rrggbbaa" || "#rrggbb" )
• $.Color( "rgba(255,255,255,1)" || "rgb(255,255,255)" )
• $.Color( anotherColorObject )  
• Has static properties available
• .names
• Color names to rgb values
• "transparent"

• it will return "undefined" for rgb unless you specify colors for these values... the transition funciton will know if the color portion is undefined that you want to scale only the alpha - allowing for something like this:

  $.Color("#abcdef").transition("transparent", 0.5) - animating to the value "transparent" will use #abcdef the whole time...

• .support 

• .rgba - The browser supports native rgba() 

The jQuery.Color.fn / prototype methods

     Getters 

• .red() - returns the "red" component of the color ( int 0-255)
• .blue() - returns the "blue" component of the color ( int 0-255)
• .green() - returns the "green" component of the color ( int 0-255)
• .alpha() - returns the "alpha" component of the color ( int 0-255) 
• .rgba() - returns the rgba "tupple" as an array: [ red, green, blue, alpha ] 

     Setters

• .red( intOrString ) - sets red to specified value and returns a copy of the color object
• .blue( intOrString ) - sets blue to specified value and returns a copy of the color object
• .green( intOrString ) - sets green to specified value and returns a copy of the color object
• .alpha( intOrString ) - sets alpha to specified value and returns a copy of the color object 
• .rgba( redOrArrayOrObject, green, blue, alpha ) - assigns all values and returns a copy of the color object 
• rgba( red, green, blue, alpha )
• rgba( { red: red, green: green, blue: blue, alpha: alpha } )
• rgba( [ red, green, blue, alpha ] )

     Manipulation

• transition( color, distance ) - the color distance from the objects color to the provided color, between a distance of 0.0 and 1.0
• blend( opaqueColor ) - applies the objects color on top of the provided color using alpha compositing

     Other methods

• toRgbaString() - returns string as css, e.g. "rgba( 255,255,255,1 )"
• toHexString( includeAlpha ) = returns hex value with pound sign, e.g., "#123456"
• includeAlpha is true, returns string in #rrggbbaa format
• includeAlpha is false, returns string in #rrggbb format 

Internal Storage/Options

• Internally, rgba is stored as
• colorObject._rgba[0] = red
• colorObject._rgba[1] = green
• colorObject._rgba[2] = blue
• colorObject._rgba[3] = alpha

CSS Hooks

• Allow setting css values to a Color
• Calculate "transparent" colors based on nearest background color in browsers which can't support rgba 

Animation Support

• Reproducing the same animation options available from the original jQuery-color with the new library

Milestone 2: HSL Support - Ready for Review

4 - Markup & Style

N/A

5 - Latest version of plugin:

https://github.com/gnarf37/jquery-color

6 - Open issues being discussed

• Should detect support for hsla/rgba - should these toString functions return what the browser supports? Something like:
• toRgbaString() - returns what the browser supports, rgb or rgba
• toRgbaString( false ) - returns if alpha false, that is, rgb(255,255,255)
• toRgbaString( true ) - returns if alpha true, that is, rgba(255,255,255,1);