From 195690f68081d2bf0f873cfdda6e23d09c5f285f Mon Sep 17 00:00:00 2001
From: David Clark <dclark@mapbox.com>
Date: Thu, 14 Dec 2017 13:40:25 -0700
Subject: [PATCH] Add Color#toString, expose Color publicly, document it

---
 src/style-spec/style-spec.js  |  1 +
 src/style-spec/util/color.js  | 30 ++++++++++++++++++++++++++++--
 test/unit/style-spec/color.js |  8 ++++++++
 3 files changed, 37 insertions(+), 2 deletions(-)

diff --git a/src/style-spec/style-spec.js b/src/style-spec/style-spec.js
index 45072481522..fbdd018a274 100644
--- a/src/style-spec/style-spec.js
+++ b/src/style-spec/style-spec.js
@@ -61,6 +61,7 @@ exports.ValidationError = require('./error/validation_error');
 exports.ParsingError = require('./error/parsing_error');
 exports.expression = require('./expression');
 exports.featureFilter = require('./feature_filter');
+exports.Color = require('./util/color');
 
 exports.function = require('./function');
 exports.function.convertFunction = require('./function/convert');
diff --git a/src/style-spec/util/color.js b/src/style-spec/util/color.js
index 3e19d2980a0..671478dba7b 100644
--- a/src/style-spec/util/color.js
+++ b/src/style-spec/util/color.js
@@ -3,8 +3,14 @@
 const {parseCSSColor} = require('csscolorparser');
 
 /**
- * An RGBA color value. All components are in the range [0, 1] and R, B, and G are premultiplied by A.
- * @private
+ * An RGBA color value. Create instances from color strings using the static
+ * method `Color.parse`. The constructor accepts RGB channel values in the range
+ * `[0, 1]`, premultiplied by A.
+ *
+ * @param {number} r The red channel.
+ * @param {number} g The green channel.
+ * @param {number} b The blue channel.
+ * @param {number} a The alpha channel.
  */
 class Color {
     r: number;
@@ -23,6 +29,10 @@ class Color {
     static white: Color;
     static transparent: Color;
 
+    /**
+     * Parses valid CSS color strings and returns a `Color` instance.
+     * @returns A `Color` instance, or `undefined` if the input is not a valid color string.
+     */
     static parse(input: ?string): Color | void {
         if (!input) {
             return undefined;
@@ -48,6 +58,22 @@ class Color {
             rgba[3]
         );
     }
+
+    /**
+     * Returns an RGBA string representing the color value.
+     *
+     * @returns An RGBA string.
+     * @example
+     * var purple = new Color.parse('purple');
+     * purple.toString; // = "rgba(128,0,128,1)"
+     * var translucentGreen = new Color.parse('rgba(26, 207, 26, .73)');
+     * translucentGreen.toString(); // = "rgba(26,207,26,0.73)"
+     */
+    toString(): string {
+        const transformRgb = (value: number) => Math.round(value * 255 / this.a);
+        const rgb = [this.r, this.g, this.b].map(transformRgb);
+        return `rgba(${rgb.concat(this.a).join(',')})`;
+    }
 }
 
 Color.black = new Color(0, 0, 0, 1);
diff --git a/test/unit/style-spec/color.js b/test/unit/style-spec/color.js
index 64e0ca55603..a874bee9217 100644
--- a/test/unit/style-spec/color.js
+++ b/test/unit/style-spec/color.js
@@ -13,3 +13,11 @@ test('Color.parse', (t) => {
     t.deepEqual(Color.parse(undefined), undefined);
     t.end();
 });
+
+test('Color#toString', (t) => {
+    const purple = Color.parse('purple');
+    t.equal(purple && purple.toString(), 'rgba(128,0,128,1)');
+    const translucentGreen = Color.parse('rgba(26, 207, 26, .73)');
+    t.equal(translucentGreen && translucentGreen.toString(), 'rgba(26,207,26,0.73)');
+    t.end();
+});