[Summary view] [Print] [Text view]

   1  /*
   2  YUI 3.17.2 (build 9c3c78e)
   3  Copyright 2014 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                  Y.log('Invalid value: count must be greater than 1.', 'error', 'Y.Color.getMonochrome');
 216                  return str;
 217              }
 218  
 219              step = 100 / (count - 1);
 220  
 221              for (; i <= 100; i += step) {
 222                  _c[2] = Math.max(Math.min(i, 100), 0);
 223                  colors.push(_c.concat());
 224              }
 225  
 226              l = colors.length;
 227  
 228              for (i=0; i<l; i++) {
 229                  colors[i] = Harmony._finish(colors[i], to);
 230              }
 231  
 232              return colors;
 233          },
 234  
 235          /**
 236          Creates an Array of similar colors. Returned Array is prepended
 237             with the color provided followed a number of colors decided
 238             by count
 239          @public
 240          @method getSimilar
 241          @param {String} str
 242          @param {Number} [offset]
 243          @param {Number} [count]
 244          @param {String} [to]
 245          @return {String}
 246          @since 3.8.0
 247          **/
 248          getSimilar: function(str, offset, count, to) {
 249              var c = Harmony._start(str),
 250                  offsets = [],
 251                  slOffset,
 252                  s = +(c[1]),
 253                  sMin,
 254                  sMax,
 255                  sRand,
 256                  l = +(c[2]),
 257                  lMin,
 258                  lMax,
 259                  lRand;
 260  
 261              to = to || Color.findType(str);
 262              count = count || DEF_COUNT;
 263              offset = offset || DEF_OFFSET;
 264  
 265              slOffset = (offset > 100) ? 100 : offset;
 266              sMin = Math.max(0,   s - slOffset);
 267              sMax = Math.min(100, s + slOffset);
 268              lMin = Math.max(0,   l - slOffset);
 269              lMax = Math.min(100, l + slOffset);
 270  
 271              offsets.push({});
 272              for (i = 0; i < count; i++) {
 273                  sRand = ( Math.round( (Math.random() * (sMax - sMin)) + sMin ) );
 274                  lRand = ( Math.round( (Math.random() * (lMax - lMin)) + lMin ) );
 275  
 276                  offsets.push({
 277                      h: ( Math.random() * (offset * 2)) - offset,
 278                      // because getOffset adjusts from the existing color, we
 279                      // need to adjust it negatively to get a good number for
 280                      // saturation and luminance, otherwise we get a lot of white
 281                      s: -(s - sRand),
 282                      l: -(l - lRand)
 283                  });
 284              }
 285  
 286              return Harmony._adjustOffsetAndFinish(c, offsets, to);
 287          },
 288  
 289          /**
 290          Adjusts the provided color by the offset(s) given. You may
 291            adjust hue, saturation, and/or luminance in one step.
 292          @public
 293          @method getOffset
 294          @param {String} str
 295          @param {Object} adjust
 296            @param {Number} [adjust.h]
 297            @param {Number} [adjust.s]
 298            @param {Number} [adjust.l]
 299          @param {String} [to]
 300          @return {String}
 301          @since 3.8.0
 302          **/
 303          getOffset: function(str, adjust, to) {
 304              var started = Y.Lang.isArray(str),
 305                  hsla,
 306                  type;
 307  
 308              if (!started) {
 309                  hsla = Harmony._start(str);
 310                  type = Color.findType(str);
 311              } else {
 312                  hsla = str;
 313                  type = 'hsl';
 314              }
 315  
 316              to = to || type;
 317  
 318              if (adjust.h) {
 319                  hsla[0] = ((+hsla[0]) + adjust.h) % 360;
 320              }
 321  
 322              if (adjust.s) {
 323                  hsla[1] = Math.max(Math.min((+hsla[1]) + adjust.s, 100), 0);
 324              }
 325  
 326              if (adjust.l) {
 327                  hsla[2] = Math.max(Math.min((+hsla[2]) + adjust.l, 100), 0);
 328              }
 329  
 330              if (!started) {
 331                  return Harmony._finish(hsla, to);
 332              }
 333  
 334              return hsla;
 335          },
 336  
 337          /**
 338          Returns 0 - 100 percentage of brightness from `0` (black) being the
 339            darkest to `100` (white) being the brightest.
 340          @public
 341          @method getBrightness
 342          @param {String} str
 343          @return {Number}
 344          @since 3.8.0
 345          **/
 346          getBrightness: function(str) {
 347              var c = Color.toArray(Color._convertTo(str, RGB)),
 348                  r = c[0],
 349                  g = c[1],
 350                  b = c[2],
 351                  weights = Y.Color._brightnessWeights;
 352  
 353  
 354              return Math.round(Math.sqrt(
 355                  (r * r * weights.r) +
 356                  (g * g * weights.g) +
 357                  (b * b * weights.b)
 358              ) / 255 * 100);
 359          },
 360  
 361          /**
 362          Returns a new color value with adjusted luminance so that the
 363            brightness of the return color matches the perceived brightness
 364            of the `match` color provided.
 365          @public
 366          @method getSimilarBrightness
 367          @param {String} str
 368          @param {String} match
 369          @param {String} [to]
 370          @return {String}
 371          @since 3.8.0
 372          **/
 373          getSimilarBrightness: function(str, match, to){
 374              var c = Color.toArray(Color._convertTo(str, HSL)),
 375                  b = Harmony.getBrightness(match);
 376  
 377              to = to || Color.findType(str);
 378  
 379              if (to === 'keyword') {
 380                  to = 'hex';
 381              }
 382  
 383              c[2] = Harmony._searchLuminanceForBrightness(c, b, 0, 100);
 384  
 385              str = Color.fromArray(c, Y.Color.TYPES.HSLA);
 386  
 387              return Color._convertTo(str, to);
 388          },
 389  
 390          //--------------------
 391          // PRIVATE
 392          //--------------------
 393          /**
 394          Converts the provided color from additive to subtractive returning
 395            an Array of HSLA values
 396          @private
 397          @method _start
 398          @param {String} str
 399          @return {Array}
 400          @since 3.8.0
 401          */
 402          _start: function(str) {
 403              var hsla = Color.toArray(Color._convertTo(str, HSL));
 404              hsla[0] = Harmony._toSubtractive(hsla[0]);
 405  
 406              return hsla;
 407          },
 408  
 409          /**
 410          Converts the provided HSLA values from subtractive to additive
 411            returning a converted color string
 412          @private
 413          @method _finish
 414          @param {Array} hsla
 415          @param {String} [to]
 416          @return {String}
 417          @since 3.8.0
 418          */
 419          _finish: function(hsla, to) {
 420              hsla[0] = Harmony._toAdditive(hsla[0]);
 421              hsla = 'hsla(' + hsla[0] + ', ' + hsla[1] + '%, ' + hsla[2] + '%, ' + hsla[3] + ')';
 422  
 423              if (to === 'keyword') {
 424                  to = 'hex';
 425              }
 426  
 427              return Color._convertTo(hsla, to);
 428          },
 429  
 430          /**
 431          Adjusts the hue degree from subtractive to additive
 432          @private
 433          @method _toAdditive
 434          @param {Number} hue
 435          @return {Number} Converted additive hue
 436          @since 3.8.0
 437          */
 438          _toAdditive: function(hue) {
 439              hue = Y.Color._constrainHue(hue);
 440  
 441              if (hue <= 180) {
 442                  hue /= 1.5;
 443              } else if (hue < 240) {
 444                  hue = 120 + (hue - 180) * 2;
 445              }
 446  
 447              return Y.Color._constrainHue(hue, 10);
 448          },
 449  
 450          /**
 451          Adjusts the hue degree from additive to subtractive
 452          @private
 453          @method _toSubtractive
 454          @param {Number} hue
 455          @return {Number} Converted subtractive hue
 456          @since 3.8.0
 457          */
 458          _toSubtractive: function(hue) {
 459              hue = Y.Color._constrainHue(hue);
 460  
 461              if (hue <= 120) {
 462                  hue *= 1.5;
 463              } else if (hue < 240) {
 464                  hue = 180 + (hue - 120) / 2;
 465              }
 466  
 467              return Y.Color._constrainHue(hue, 10);
 468          },
 469  
 470          /**
 471          Contrain the hue to a value between 0 and 360 for calculations
 472              and real color wheel value space. Provide a precision value
 473              to round return value to a decimal place
 474          @private
 475          @method _constrainHue
 476          @param {Number} hue
 477          @param {Number} [precision]
 478          @return {Number} Constrained hue value
 479          @since 3.8.0
 480          **/
 481          _constrainHue: function(hue, precision) {
 482              while (hue < 0) {
 483                  hue += 360;
 484              }
 485              hue %= 360;
 486  
 487              if (precision) {
 488                  hue = Math.round(hue * precision) / precision;
 489              }
 490  
 491              return hue;
 492          },
 493  
 494          /**
 495          Brightness weight factors for perceived brightness calculations
 496  
 497          "standard" values are listed as R: 0.241, G: 0.691, B: 0.068
 498          These values were changed based on grey scale comparison of hsl
 499            to new hsl where brightness is said to be within plus or minus 0.01.
 500          @private
 501          @property _brightnessWeights
 502          @since 3.8.0
 503          */
 504          _brightnessWeights: {
 505              r: 0.221,
 506              g: 0.711,
 507              b: 0.068
 508          },
 509  
 510          /**
 511          Calculates the luminance as a mid range between the min and max
 512            to match the brightness level provided
 513          @private
 514          @method _searchLuminanceForBrightness
 515          @param {Array} color HSLA values
 516          @param {Number} brightness Brightness to be matched
 517          @param {Number} min Minimum range for luminance
 518          @param {Number} max Maximum range for luminance
 519          @return {Number} Found luminance to achieve requested brightness
 520          @since 3.8.0
 521          **/
 522          _searchLuminanceForBrightness: function(color, brightness, min, max) {
 523              var luminance = (max + min) / 2,
 524                  b;
 525  
 526              color[2] = luminance;
 527              b = Harmony.getBrightness(Color.fromArray(color, Y.Color.TYPES.HSL));
 528  
 529              if (b + 2 > brightness && b - 2 < brightness) {
 530                  return luminance;
 531              } else if (b > brightness) {
 532                  return Harmony._searchLuminanceForBrightness(color, brightness, min, luminance);
 533              } else {
 534                  return Harmony._searchLuminanceForBrightness(color, brightness, luminance, max);
 535              }
 536          },
 537  
 538          /**
 539          Takes an HSL array, and an array of offsets and returns and array
 540              of colors that have been adjusted. The returned colors will
 541              match the array of offsets provided. If you wish you have the
 542              same color value returned, you can provide null or an empty
 543              object to the offsets. The returned array will contain color
 544              value strings that have been adjusted from subtractive to
 545              additive.
 546          @private
 547          @method _adjustOffsetAndFinish
 548          @param {Array} color
 549          @param {Array} offsets
 550          @param {String} to
 551          @return {Array}
 552          @since 3.8.0
 553          **/
 554          _adjustOffsetAndFinish: function(color, offsets, to) {
 555              var colors = [],
 556                  i,
 557                  l = offsets.length,
 558                  _c;
 559  
 560              for (i = 0; i < l; i++ ) {
 561                  _c = color.concat();
 562                  if (offsets[i]) {
 563                      _c = Harmony.getOffset(_c, offsets[i]);
 564                  }
 565                  colors.push(Harmony._finish(_c, to));
 566              }
 567  
 568              return colors;
 569          }
 570  
 571      };
 572  
 573  Y.Color = Y.mix(Y.Color, Harmony);
 574  
 575  
 576  }, '3.17.2', {"requires": ["color-hsl"]});