feat(expandShorthandProperty): Add "includeInitialValues" paramater

- add additional paramter to expandShorthand property to fill in initial values that are not explicitly set in a shorthand declaration
- update README and tests accordingly

fixes #1

Author: Mahir Shah

README.md

@@ -17,7 +17,7 @@
     - [Examples](#examples-1)
   - [getShorthandComputedProperties(property: string, [recursivelyResolve=false]): Array](#getshorthandcomputedpropertiesproperty-string-recursivelyresolvefalse-array)
       - [Examples](#examples-2)
-  - [expandShorthandProperty(property: string, value: string, [recursivelyResolve=false]): Object](#expandshorthandpropertyproperty-string-value-string-recursivelyresolvefalse-object)
+  - [expandShorthandProperty(property: string, value: string, [recursivelyResolve=false], [includeInitialValues=false]): Object](#expandshorthandpropertyproperty-string-value-string-recursivelyresolvefalse-includeinitialvaluesfalse-object)
       - [Examples](#examples-3)
   - [Developer/Contribution HOWTO](#developercontribution-howto)
 
@@ -199,7 +199,7 @@ getShorthandComputedProperties('border', true);
 // -> []
 ``` 
 
-### [expandShorthandProperty(property: string, value: string, [recursivelyResolve=false]): Object](./src/expandShorthandProperty.js)
+### [expandShorthandProperty(property: string, value: string, [recursivelyResolve=false], [includeInitialValues=false]): Object](./src/expandShorthandProperty.js)
 
 Given a property and value attempts to expand the value into its longhand equivalents. Returns an object
 mapping the property longhand names to the longhand values. If the property cannot be expanded (i.e. the property
@@ -208,6 +208,7 @@ is not a shorthand property) simply returns an object mapping the original prope
  * propertyName - the property name for the given value
  * propertyValue - the value of the property
  * [recursivelyResolve=false] - recursively resolve additional longhand properties if the shorthands expand to additional shorthands. For example, the border property expands to border-width, which expands further to border-left-width, border-right-width, etc.
+ * [includeInitialValues=false] - when expanding the shorthand property, fill in any missing longhand values with their initial value. For example, the property declaration "border: 1px" only explicitly sets the "border-width" longhand property. If this param is true, the returned object will fill in the initial values for "border-style" and "border-color". By default, the returned object will only contain the "border-width".
  * throws {[ParseError](./src/errors/ParseError.js)} - if the propertyValue cannot be parsed.
  * throws {[UnknownPropertyError](./src/errors/UnknownPropertyError.js)} - if the propertyName is not defined in mdn.
  * throws {[UnsupportedPropertyError](./src/errors/UnsupportedPropertyError.js)} - if the propertyName is a shorthand property, but we don't support expanding it yet.
@@ -217,12 +218,8 @@ Currently supports the following properties:
   - animation
   - background
   - border
-  - border-block-end
-  - border-block-start
   - border-bottom
   - border-color
-  - border-inline-end
-  - border-inline-start
   - border-left
   - border-radius
   - border-right

src/expandShorthandProperty.js

@@ -42,6 +42,12 @@ const R_BLOCK_COMMENT = /\/\*.*?\*\//g;
  *                                              expand to additional shorthands. For example, the border property
  *                                              expands to border-width, which expands further to border-left-width,
  *                                              border-right-width, etc.
+ * @param {boolean} [includeInitialValues=false] - when expanding the shorthand property, fill in any missing longhand
+ *                                                 values with their initial value. For example, the property
+ *                                                 declaration "border: 1px" only explicitly sets the "border-width"
+ *                                                 longhand property. If this param is true, the returned object will
+ *                                                 fill in the initial values for "border-style" and "border-color". By
+ *                                                 default, the returned object will only contain the "border-width".
  * @return {Object} - object mapping longhand property names to values
  *
  * @throws {ParseError} - if the propertyValue cannot be parsed.
@@ -65,9 +71,11 @@ const R_BLOCK_COMMENT = /\/\*.*?\*\//g;
  *  'flex-shrink': 'initial',
  *  'flex-basis': 'initial',
  * }
- * TODO: add another param to include initial values for values not set
  */
-module.exports = function expandShorthandProperty(propertyName, propertyValue, recursivelyResolve = false) {
+module.exports = function expandShorthandProperty(propertyName,
+  propertyValue,
+  recursivelyResolve = false,
+  includeInitialValues = false) {
   if (!properties[propertyName]) {
     throw new UnknownPropertyError(propertyName);
   } else if (!isShorthandProperty(propertyName)) {
@@ -95,16 +103,23 @@ module.exports = function expandShorthandProperty(propertyName, propertyValue, r
   }
 
   // get the first parsing and use the formatter for the specific shorthand type for this property
+  const { shorthandType } = shorthandProperties[propertyName];
   const [rootNode] = parser.results;
   LocationIndexTracker.reset();
-  const shorthandType = shorthandProperties[propertyName].shorthandType;
   const propertyExpansion = shorthandPropertyTypeToActionDictionaryFactoryMap[shorthandType]
     .format(propertyName, rootNode, formattedPropertyValue);
+  const initialValuePropertyMap = getShorthandComputedProperties(propertyName, true)
+    .reduce((initialValueMap, propertyName) => (Array.isArray(properties[propertyName].initial)
+      ? initialValueMap
+      : Object.assign({ [propertyName]: properties[propertyName].initial }, initialValueMap)), {});
+  const expandedProperties = includeInitialValues
+    ? Object.assign(initialValuePropertyMap, propertyExpansion)
+    : propertyExpansion;
 
   // if we need to recursively resolve, go through each value and expand it.
   return recursivelyResolve ? Object.entries(propertyExpansion)
       .reduce((propertyExpansion, [name, value]) => (
-        Object.assign(expandShorthandProperty(name, value, true), propertyExpansion)
-      ), propertyExpansion)
-    : propertyExpansion;
+        Object.assign(propertyExpansion, expandShorthandProperty(name, value, true))
+      ), expandedProperties)
+    : expandedProperties;
 };

test/ExpandShorthandPropertyTest.js

@@ -177,6 +177,23 @@ describe('expandShorthandProperty', function () {
       });
     });
 
+    it('should return expanded border with style, color with recursively resolved properties', function () {
+      const result = expandShorthandProperty('border', 'solid black', true);
+
+      assert.deepEqual(result, {
+        'border-style': 'solid',
+        'border-color': 'black',
+        'border-bottom-style': 'solid',
+        'border-left-style': 'solid',
+        'border-right-style': 'solid',
+        'border-top-style': 'solid',
+        'border-bottom-color': 'black',
+        'border-right-color': 'black',
+        'border-left-color': 'black',
+        'border-top-color': 'black',
+      });
+    });
+
     it('should return expanded border with just color', function () {
       const result = expandShorthandProperty('border', 'black');
 
@@ -862,7 +879,7 @@ describe('expandShorthandProperty', function () {
       assert.deepEqual(result, {
         'font-stretch': 'ultra-condensed',
         'font-size': '16px',
-        'font-family': 'sans-serif'
+        'font-family': 'sans-serif',
       });
     });
 
@@ -894,4 +911,40 @@ describe('expandShorthandProperty', function () {
       });
     });
   });
+
+  describe('include initial values', function () {
+    it('should include initial values for font', function () {
+      const result = expandShorthandProperty('font', 'ultra-condensed 16px sans-serif', true, true);
+
+      assert.deepEqual(result, {
+        'font-family': 'sans-serif',
+        'font-size': '16px',
+        'font-stretch': 'ultra-condensed',
+        'font-style': 'normal',
+        'font-variant': 'normal',
+        'font-weight': 'normal',
+        'line-height': 'normal',
+      });
+    });
+
+    it('should include initial values for border', function () {
+      const result = expandShorthandProperty('border', '1px', true, true);
+
+      assert.deepEqual(result, {
+        'border-bottom-color': 'currentcolor',
+        'border-bottom-style': 'none',
+        'border-bottom-width': '1px',
+        'border-left-color': 'currentcolor',
+        'border-left-style': 'none',
+        'border-left-width': '1px',
+        'border-right-color': 'currentcolor',
+        'border-right-style': 'none',
+        'border-right-width': '1px',
+        'border-top-color': 'currentcolor',
+        'border-top-style': 'none',
+        'border-top-width': '1px',
+        'border-width': '1px',
+      });
+    });
+  });
 });