lib/yuilib/3.13.0/color-harmony/color-harmony.js

   1 /*
   2 YUI 3.13.0 (build 508226d)
   3 Copyright 2013 Yahoo! Inc. All rights reserved.
   4 Licensed under the BSD License.
   5 http://yuilibrary.com/license/
   6 */
   7
   8 YUI.add('color-harmony', function (Y, NAME) {
   9
  10 /**
  11 Color Harmony provides methods useful for color combination discovery.
  12
  13 @module color
  14 @submodule color-harmony
  15 @class Harmony
  16 @namespace Color
  17 @since 3.8.0
  18 */
  19 var HSL = 'hsl',
  20     RGB = 'rgb',
  21
  22     SPLIT_OFFSET = 30,
  23     ANALOGOUS_OFFSET = 10,
  24     TRIAD_OFFSET = 360/3,
  25     TETRAD_OFFSET = 360/6,
  26     SQUARE_OFFSET = 360/4 ,
  27
  28     DEF_COUNT = 5,
  29     DEF_OFFSET = 10,
  30
  31     Color = Y.Color,
  32
  33     Harmony = {
  34
  35         // Color Groups
  36         /**
  37         Returns an Array of two colors. The first color in the Array
  38           will be the color passed in. The second will be the
  39           complementary color of the color provided
  40         @public
  41         @method getComplementary
  42         @param {String} str
  43         @param {String} [to]
  44         @return {Array}
  45         @since 3.8.0
  46         **/
  47         getComplementary: function(str, to) {
  48             var c = Harmony._start(str),
  49                 offsets = [];
  50
  51             to = to || Color.findType(str);
  52
  53             offsets.push({});
  54             offsets.push({ h: 180 });
  55
  56             return Harmony._adjustOffsetAndFinish(c, offsets, to);
  57         },
  58
  59         /**
  60         Returns an Array of three colors. The first color in the Array
  61           will be the color passed in. The second two will be split
  62           complementary colors.
  63         @public
  64         @method getSplit
  65         @param {String} str
  66         @param {Number} [offset]
  67         @param {String} [to]
  68         @return {String}
  69         @since 3.8.0
  70         **/
  71         getSplit: function(str, offset, to) {
  72             var c = Harmony._start(str),
  73                 offsets = [];
  74
  75             offset = offset || SPLIT_OFFSET;
  76
  77             to = to || Color.findType(str);
  78
  79             offsets.push({});
  80             offsets.push({ h: 180 + offset });
  81             offsets.push({ h: 180 - offset });
  82
  83             return Harmony._adjustOffsetAndFinish(c, offsets, to);
  84         },
  85
  86         /**
  87         Returns an Array of five colors. The first color in the Array
  88           will be the color passed in. The remaining four will be
  89           analogous colors two in either direction from the initially
  90           provided color.
  91         @public
  92         @method getAnalogous
  93         @param {String} str
  94         @param {Number} [offset]
  95         @param {String} [to]
  96         @return {String}
  97         @since 3.8.0
  98         **/
  99         getAnalogous: function(str, offset, to) {
 100             var c = Harmony._start(str),
 101                 offsets = [];
 102
 103             offset = offset || ANALOGOUS_OFFSET;
 104             to = to || Color.findType(str);
 105
 106             offsets.push({});
 107             offsets.push({ h: offset });
 108             offsets.push({ h: offset * 2 });
 109             offsets.push({ h: -offset });
 110             offsets.push({ h: -offset * 2 });
 111
 112             return Harmony._adjustOffsetAndFinish(c, offsets, to);
 113         },
 114
 115         /**
 116         Returns an Array of three colors. The first color in the Array
 117           will be the color passed in. The second two will be equidistant
 118           from the start color and each other.
 119         @public
 120         @method getTriad
 121         @param {String} str
 122         @param {String} [to]
 123         @return {String}
 124         @since 3.8.0
 125         **/
 126         getTriad: function(str, to) {
 127             var c = Harmony._start(str),
 128                 offsets = [];
 129
 130             to = to || Color.findType(str);
 131
 132             offsets.push({});
 133             offsets.push({ h: TRIAD_OFFSET });
 134             offsets.push({ h: -TRIAD_OFFSET });
 135
 136             return Harmony._adjustOffsetAndFinish(c, offsets, to);
 137         },
 138
 139         /**
 140         Returns an Array of four colors. The first color in the Array
 141           will be the color passed in. The remaining three colors are
 142           equidistant offsets from the starting color and each other.
 143         @public
 144         @method getTetrad
 145         @param {String} str
 146         @param {Number} [offset]
 147         @param {String} [to]
 148         @return {String}
 149         @since 3.8.0
 150         **/
 151         getTetrad: function(str, offset, to) {
 152             var c = Harmony._start(str),
 153                 offsets = [];
 154
 155             offset = offset || TETRAD_OFFSET;
 156             to = to || Color.findType(str);
 157
 158             offsets.push({});
 159             offsets.push({ h: offset });
 160             offsets.push({ h: 180 });
 161             offsets.push({ h: 180 + offset });
 162
 163             return Harmony._adjustOffsetAndFinish(c, offsets, to);
 164         },
 165
 166         /**
 167         Returns an Array of four colors. The first color in the Array
 168           will be the color passed in. The remaining three colors are
 169           equidistant offsets from the starting color and each other.
 170         @public
 171         @method getSquare
 172         @param {String} str
 173         @param {String} [to]
 174         @return {String}
 175         @since 3.8.0
 176         **/
 177         getSquare: function(str, to) {
 178             var c = Harmony._start(str),
 179                 offsets = [];
 180
 181             to = to || Color.findType(str);
 182
 183             offsets.push({});
 184             offsets.push({ h: SQUARE_OFFSET });
 185             offsets.push({ h: SQUARE_OFFSET * 2 });
 186             offsets.push({ h: SQUARE_OFFSET * 3 });
 187
 188             return Harmony._adjustOffsetAndFinish(c, offsets, to);
 189         },
 190
 191         /**
 192         Calculates lightness offsets resulting in a monochromatic Array
 193           of values.
 194         @public
 195         @method getMonochrome
 196         @param {String} str
 197         @param {Number} [count]
 198         @param {String} [to]
 199         @return {String}
 200         @since 3.8.0
 201         **/
 202         getMonochrome: function(str, count, to) {
 203             var c = Harmony._start(str),
 204                 colors = [],
 205                 i = 0,
 206                 l,
 207                 step,
 208                 _c = c.concat();
 209
 210             count = count || DEF_COUNT;
 211             to = to || Color.findType(str);
 212
 213
 214             if (count < 2) {
 215                 return str;
 216             }
 217
 218             step = 100 / (count - 1);
 219
 220             for (; i <= 100; i += step) {
 221                 _c[2] = Math.max(Math.min(i, 100), 0);
 222                 colors.push(_c.concat());
 223             }
 224
 225             l = colors.length;
 226
 227             for (i=0; i<l; i++) {
 228                 colors[i] = Harmony._finish(colors[i], to);
 229             }
 230
 231             return colors;
 232         },
 233
 234         /**
 235         Creates an Array of similar colors. Returned Array is prepended
 236            with the color provided followed a number of colors decided
 237            by count
 238         @public
 239         @method getSimilar
 240         @param {String} str
 241         @param {Number} [offset]
 242         @param {Number} [count]
 243         @param {String} [to]
 244         @return {String}
 245         @since 3.8.0
 246         **/
 247         getSimilar: function(str, offset, count, to) {
 248             var c = Harmony._start(str),
 249                 offsets = [],
 250                 slOffset,
 251                 s = +(c[1]),
 252                 sMin,
 253                 sMax,
 254                 sRand,
 255                 l = +(c[2]),
 256                 lMin,
 257                 lMax,
 258                 lRand;
 259
 260             to = to || Color.findType(str);
 261             count = count || DEF_COUNT;
 262             offset = offset || DEF_OFFSET;
 263
 264             slOffset = (offset > 100) ? 100 : offset;
 265             sMin = Math.max(0,   s - slOffset);
 266             sMax = Math.min(100, s + slOffset);
 267             lMin = Math.max(0,   l - slOffset);
 268             lMax = Math.min(100, l + slOffset);
 269
 270             offsets.push({});
 271             for (i = 0; i < count; i++) {
 272                 sRand = ( Math.round( (Math.random() * (sMax - sMin)) + sMin ) );
 273                 lRand = ( Math.round( (Math.random() * (lMax - lMin)) + lMin ) );
 274
 275                 offsets.push({
 276                     h: ( Math.random() * (offset * 2)) - offset,
 277                     // because getOffset adjusts from the existing color, we
 278                     // need to adjust it negatively to get a good number for
 279                     // saturation and luminance, otherwise we get a lot of white
 280                     s: -(s - sRand),
 281                     l: -(l - lRand)
 282                 });
 283             }
 284
 285             return Harmony._adjustOffsetAndFinish(c, offsets, to);
 286         },
 287
 288         /**
 289         Adjusts the provided color by the offset(s) given. You may
 290           adjust hue, saturation, and/or luminance in one step.
 291         @public
 292         @method getOffset
 293         @param {String} str
 294         @param {Object} adjust
 295           @param {Number} [adjust.h]
 296           @param {Number} [adjust.s]
 297           @param {Number} [adjust.l]
 298         @param {String} [to]
 299         @return {String}
 300         @since 3.8.0
 301         **/
 302         getOffset: function(str, adjust, to) {
 303             var started = Y.Lang.isArray(str),
 304                 hsla,
 305                 type;
 306
 307             if (!started) {
 308                 hsla = Harmony._start(str);
 309                 type = Color.findType(str);
 310             } else {
 311                 hsla = str;
 312                 type = 'hsl';
 313             }
 314
 315             to = to || type;
 316
 317             if (adjust.h) {
 318                 hsla[0] = ((+hsla[0]) + adjust.h) % 360;
 319             }
 320
 321             if (adjust.s) {
 322                 hsla[1] = Math.max(Math.min((+hsla[1]) + adjust.s, 100), 0);
 323             }
 324
 325             if (adjust.l) {
 326                 hsla[2] = Math.max(Math.min((+hsla[2]) + adjust.l, 100), 0);
 327             }
 328
 329             if (!started) {
 330                 return Harmony._finish(hsla, to);
 331             }
 332
 333             return hsla;
 334         },
 335
 336         /**
 337         Returns 0 - 100 percentage of brightness from `0` (black) being the
 338           darkest to `100` (white) being the brightest.
 339         @public
 340         @method getBrightness
 341         @param {String} str
 342         @return {Number}
 343         @since 3.8.0
 344         **/
 345         getBrightness: function(str) {
 346             var c = Color.toArray(Color._convertTo(str, RGB)),
 347                 r = c[0],
 348                 g = c[1],
 349                 b = c[2],
 350                 weights = Y.Color._brightnessWeights;
 351
 352
 353             return Math.round(Math.sqrt(
 354                 (r * r * weights.r) +
 355                 (g * g * weights.g) +
 356                 (b * b * weights.b)
 357             ) / 255 * 100);
 358         },
 359
 360         /**
 361         Returns a new color value with adjusted luminance so that the
 362           brightness of the return color matches the perceived brightness
 363           of the `match` color provided.
 364         @public
 365         @method getSimilarBrightness
 366         @param {String} str
 367         @param {String} match
 368         @param {String} [to]
 369         @return {String}
 370         @since 3.8.0
 371         **/
 372         getSimilarBrightness: function(str, match, to){
 373             var c = Color.toArray(Color._convertTo(str, HSL)),
 374                 b = Harmony.getBrightness(match);
 375
 376             to = to || Color.findType(str);
 377
 378             if (to === 'keyword') {
 379                 to = 'hex';
 380             }
 381
 382             c[2] = Harmony._searchLuminanceForBrightness(c, b, 0, 100);
 383
 384             str = Color.fromArray(c, Y.Color.TYPES.HSLA);
 385
 386             return Color._convertTo(str, to);
 387         },
 388
 389         //--------------------
 390         // PRIVATE
 391         //--------------------
 392         /**
 393         Converts the provided color from additive to subtractive returning
 394           an Array of HSLA values
 395         @private
 396         @method _start
 397         @param {String} str
 398         @return {Array}
 399         @since 3.8.0
 400         */
 401         _start: function(str) {
 402             var hsla = Color.toArray(Color._convertTo(str, HSL));
 403             hsla[0] = Harmony._toSubtractive(hsla[0]);
 404
 405             return hsla;
 406         },
 407
 408         /**
 409         Converts the provided HSLA values from subtractive to additive
 410           returning a converted color string
 411         @private
 412         @method _finish
 413         @param {Array} hsla
 414         @param {String} [to]
 415         @return {String}
 416         @since 3.8.0
 417         */
 418         _finish: function(hsla, to) {
 419             hsla[0] = Harmony._toAdditive(hsla[0]);
 420             hsla = 'hsla(' + hsla[0] + ', ' + hsla[1] + '%, ' + hsla[2] + '%, ' + hsla[3] + ')';
 421
 422             if (to === 'keyword') {
 423                 to = 'hex';
 424             }
 425
 426             return Color._convertTo(hsla, to);
 427         },
 428
 429         /**
 430         Adjusts the hue degree from subtractive to additive
 431         @private
 432         @method _toAdditive
 433         @param {Number} hue
 434         @return {Number} Converted additive hue
 435         @since 3.8.0
 436         */
 437         _toAdditive: function(hue) {
 438             hue = Y.Color._constrainHue(hue);
 439
 440             if (hue <= 180) {
 441                 hue /= 1.5;
 442             } else if (hue < 240) {
 443                 hue = 120 + (hue - 180) * 2;
 444             }
 445
 446             return Y.Color._constrainHue(hue, 10);
 447         },
 448
 449         /**
 450         Adjusts the hue degree from additive to subtractive
 451         @private
 452         @method _toSubtractive
 453         @param {Number} hue
 454         @return {Number} Converted subtractive hue
 455         @since 3.8.0
 456         */
 457         _toSubtractive: function(hue) {
 458             hue = Y.Color._constrainHue(hue);
 459
 460             if (hue <= 120) {
 461                 hue *= 1.5;
 462             } else if (hue < 240) {
 463                 hue = 180 + (hue - 120) / 2;
 464             }
 465
 466             return Y.Color._constrainHue(hue, 10);
 467         },
 468
 469         /**
 470         Contrain the hue to a value between 0 and 360 for calculations
 471             and real color wheel value space. Provide a precision value
 472             to round return value to a decimal place
 473         @private
 474         @method _constrainHue
 475         @param {Number} hue
 476         @param {Number} [precision]
 477         @return {Number} Constrained hue value
 478         @since 3.8.0
 479         **/
 480         _constrainHue: function(hue, precision) {
 481             while (hue < 0) {
 482                 hue += 360;
 483             }
 484             hue %= 360;
 485
 486             if (precision) {
 487                 hue = Math.round(hue * precision) / precision;
 488             }
 489
 490             return hue;
 491         },
 492
 493         /**
 494         Brightness weight factors for perceived brightness calculations
 495
 496         "standard" values are listed as R: 0.241, G: 0.691, B: 0.068
 497         These values were changed based on grey scale comparison of hsl
 498           to new hsl where brightness is said to be within plus or minus 0.01.
 499         @private
 500         @property _brightnessWeights
 501         @since 3.8.0
 502         */
 503         _brightnessWeights: {
 504             r: 0.221,
 505             g: 0.711,
 506             b: 0.068
 507         },
 508
 509         /**
 510         Calculates the luminance as a mid range between the min and max
 511           to match the brightness level provided
 512         @private
 513         @method _searchLuminanceForBrightness
 514         @param {Array} color HSLA values
 515         @param {Number} brightness Brightness to be matched
 516         @param {Number} min Minimum range for luminance
 517         @param {Number} max Maximum range for luminance
 518         @return {Number} Found luminance to achieve requested brightness
 519         @since 3.8.0
 520         **/
 521         _searchLuminanceForBrightness: function(color, brightness, min, max) {
 522             var luminance = (max + min) / 2,
 523                 b;
 524
 525             color[2] = luminance;
 526             b = Harmony.getBrightness(Color.fromArray(color, Y.Color.TYPES.HSL));
 527
 528             if (b + 2 > brightness && b - 2 < brightness) {
 529                 return luminance;
 530             } else if (b > brightness) {
 531                 return Harmony._searchLuminanceForBrightness(color, brightness, min, luminance);
 532             } else {
 533                 return Harmony._searchLuminanceForBrightness(color, brightness, luminance, max);
 534             }
 535         },
 536
 537         /**
 538         Takes an HSL array, and an array of offsets and returns and array
 539             of colors that have been adjusted. The returned colors will
 540             match the array of offsets provided. If you wish you have the
 541             same color value returned, you can provide null or an empty
 542             object to the offsets. The returned array will contain color
 543             value strings that have been adjusted from subtractive to
 544             additive.
 545         @private
 546         @method _adjustOffsetAndFinish
 547         @param {Array} color
 548         @param {Array} offsets
 549         @param {String} to
 550         @return {Array}
 551         @since 3.8.0
 552         **/
 553         _adjustOffsetAndFinish: function(color, offsets, to) {
 554             var colors = [],
 555                 i,
 556                 l = offsets.length,
 557                 _c;
 558
 559             for (i = 0; i < l; i++ ) {
 560                 _c = color.concat();
 561                 if (offsets[i]) {
 562                     _c = Harmony.getOffset(_c, offsets[i]);
 563                 }
 564                 colors.push(Harmony._finish(_c, to));
 565             }
 566
 567             return colors;
 568         }
 569
 570     };
 571
 572 Y.Color = Y.mix(Y.Color, Harmony);
 573
 574
 575 }, '3.13.0', {"requires": ["color-hsl"]});