feat(formats): Add outputReferences support to scss/map-deep

Use the `formattedVariables` within the `scss/map-deep` formatter
to add support for the `outputReferences` option.
Closes: amzn#712

A side effect of this change is that `scss/map-deep` also
supports the `themeable` token property. For backward compatibility
changes have been made so tokens default to being themeable
with `scss/map-deep`, unlike for `scss/variables` where tokens
are not themeable by default. See amzn#474

__integration__/scss.test.js

@@ -48,6 +48,13 @@ describe(`integration`, () => {
             destination: `map-deep.scss`,
             format: `scss/map-deep`,
             mapName: 'design-system-tokens'
+          },{
+            destination: `map-deep-with-references.scss`,
+            format: `scss/map-deep`,
+            mapName: 'design-system-tokens',
+            options: {
+              outputReferences: true
+            }
           }]
         }
       }
@@ -117,10 +124,25 @@ describe(`integration`, () => {
       it(`should match snapshot`, () => {
         expect(output).toMatchSnapshot();
       });
+
+      describe(`with outputReferences`, () => {
+        const output = fs.readFileSync(`${buildPath}map-deep-with-references.scss`, { encoding: 'UTF-8' });
+        it(`should have a valid scss syntax`, () => {
+          const result = scss.renderSync({
+            data: output,
+          });
+          expect(result.css).toBeDefined();
+        });
+
+        it(`should match snapshot`, () => {
+          expect(output).toMatchSnapshot();
+        });
+      });
+
     });
   });
 });
 
 afterAll(() => {
   fs.emptyDirSync(buildPath);
-});
+});

__tests__/formats/__snapshots__/all.test.js.snap

@@ -616,8 +616,7 @@ exports[`formats all should match less/variables snapshot 1`] = `
 `;
 
 exports[`formats all should match sass/map-deep snapshot 1`] = `
-"
-/**
+"/**
  * Do not edit directly
  * Generated on Sat, 01 Jan 2000 00:00:00 GMT
  */
@@ -629,6 +628,7 @@ $tokens: (
     'red': $color_red
   )
 );
+
 "
 `;
 
@@ -655,8 +655,7 @@ exports[`formats all should match scss/icons snapshot 1`] = `
 `;
 
 exports[`formats all should match scss/map-deep snapshot 1`] = `
-"
-/**
+"/**
  * Do not edit directly
  * Generated on Sat, 01 Jan 2000 00:00:00 GMT
  */
@@ -668,6 +667,7 @@ $tokens: (
     'red': $color_red
   )
 );
+
 "
 `;
 

__tests__/formats/__snapshots__/scssMaps.test.js.snap

@@ -1,8 +1,7 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[`formats scss/map-deep scss/map-deep snapshot 1`] = `
-"
-/**
+"/**
  * Do not edit directly
  * Generated on Sat, 01 Jan 2000 00:00:00 GMT
  */
@@ -32,6 +31,7 @@ $tokens: (
     )
   )
 );
+
 "
 `;
 

lib/common/formatHelpers/createPropertyFormatter.js

@@ -45,9 +45,10 @@ const defaultFormatting = {
  * @param {Dictionary} options.dictionary - The dictionary object sent to the formatter function
  * @param {String} options.format - Available formats are: 'css', 'sass', 'less', and 'stylus'. If you want to customize the format and can't use one of those predefined formats, use the `formatting` option
  * @param {Object} options.formatting - Custom formatting properties that define parts of a declaration line in code. The configurable strings are: prefix, indentation, separator, suffix, and commentStyle. Those are used to generate a line like this: `${indentation}${prefix}${prop.name}${separator} ${prop.value}${suffix}`
+ * @param {Boolean} options.themeable_default [false] - Whether tokens should default to being themeable.
  * @returns {Function}
  */
-function createPropertyFormatter({outputReferences, dictionary, format, formatting={}}) {
+function createPropertyFormatter({ outputReferences, dictionary, format, formatting = {}, themeable_default = false }) {
   let {prefix, commentStyle, indentation, separator, suffix} = Object.assign({}, defaultFormatting, formatting);
 
   switch(format) {
@@ -117,7 +118,8 @@ function createPropertyFormatter({outputReferences, dictionary, format, formatti
 
     to_ret_prop += prop.attributes.category === 'asset' ? `"${value}"` : value;
 
-    if (format == 'sass' && prop.themeable === true) {
+    const themeable = typeof prop.themeable === 'boolean' ? prop.themeable : themeable_default;
+    if (format === 'sass' && themeable) {
       to_ret_prop += ' !default';
     }
 
@@ -135,4 +137,4 @@ function createPropertyFormatter({outputReferences, dictionary, format, formatti
   }
 }
 
-module.exports = createPropertyFormatter;
+module.exports = createPropertyFormatter;

lib/common/formatHelpers/formattedVariables.js

@@ -27,6 +27,7 @@ const defaultFormatting = {
  * @param {Object} options.dictionary - The dictionary object that gets passed to the formatter method.
  * @param {Boolean} options.outputReferences - Whether or not to output references
  * @param {Object} options.formatting - Custom formatting properties that define parts of a declaration line in code. This will get passed to `formatHelpers.createPropertyFormatter` and used for the `lineSeparator` between lines of code.
+ * @param {Boolean} options.themeable_default [false] - Whether tokens should default to being themeable.
  * @returns {String}
  * @example
  * ```js
@@ -38,7 +39,7 @@ const defaultFormatting = {
  * });
  * ```
  */
-function formattedVariables({format, dictionary, outputReferences=false, formatting={}}) {
+function formattedVariables({ format, dictionary, outputReferences = false, formatting = {}, themeable_default = false}) {
   let {allTokens} = dictionary;
 
   let {lineSeparator} = Object.assign({}, defaultFormatting, formatting);
@@ -56,9 +57,9 @@ function formattedVariables({format, dictionary, outputReferences=false, formatt
   }
 
   return allTokens
-    .map(createPropertyFormatter({ outputReferences, dictionary, format, formatting }))
+    .map(createPropertyFormatter({ outputReferences, dictionary, format, formatting, themeable_default }))
     .filter(function(strVal) { return !!strVal })
     .join(lineSeparator);
 }
 
-module.exports = formattedVariables;
+module.exports = formattedVariables;

lib/common/formats.js

@@ -84,6 +84,8 @@ module.exports = {
    *
    * @memberof Formats
    * @kind member
+   * @param {Object} options
+   * @param {Boolean} [options.outputReferences=false] - Whether or not to keep [references](/#/formats?id=references-in-output-files) (a -> b -> c) in the output.
    * @example
    * ```scss
    * $color-background-base: #f0f0f0 !default;
@@ -100,8 +102,13 @@ module.exports = {
    * ```
    */
   'scss/map-deep': function({dictionary, options, file}) {
-    const template = _template(fs.readFileSync(__dirname + '/templates/scss/map-deep.template'));
-    return template({dictionary, file, options, fileHeader});
+    const mapTemplate = _template(fs.readFileSync(__dirname + '/templates/scss/map-deep.template'));
+
+    const { outputReferences } = options;
+    return fileHeader({ file, commentStyle: 'long' }) +
+      formattedVariables({ format: 'sass', dictionary, outputReferences, themeable_default: true })
+      + '\n' +
+      mapTemplate({dictionary, file});
   },
 
   // This will soon be removed, is left here only for backwards compatibility
@@ -1165,4 +1172,4 @@ declare const ${moduleName}: ${JSON.stringify(treeWalker(dictionary.tokens), nul
 // Mark which formats are nested
 module.exports['json/nested'].nested = true;
 module.exports['javascript/module'].nested = true;
-module.exports['javascript/object'].nested = true;
+module.exports['javascript/object'].nested = true;

lib/common/templates/scss/map-deep.template

@@ -13,21 +13,7 @@
 // express or implied. See the License for the specific language governing
 // permissions and limitations under the License.
 %>
-<%= fileHeader({file, commentStyle: 'long'}) %><%
-    // output the list of tokens as Sass variables
-    //
-    dictionary.allTokens.forEach(function(prop) {
-        var output = '';
-        output += '$' + prop.name + ': ' + (prop.attributes.category==='asset' ? '"'+prop.value+'"' : prop.value) + ' !default;'
-        if(prop.comment) {
-        output += ' // ' + prop.comment;
-        }
-        output += '\n';
-        print(output);
-    });
-
-    print('\n');
-
+<%
     // output the list of tokens as a Sass nested map
     // (the values are pointing to the variables)
     //
@@ -52,4 +38,4 @@
         }
         return output;
     }
-%>
+%>