Merge pull request #2 from css-blocks/cleanup

Cleanup

Author: mahirshah

README.md

@@ -17,7 +17,7 @@
     - [Examples](#examples-1)
   - [getShorthandComputedProperties(property: string): Array](#getshorthandcomputedpropertiesproperty-string-array)
       - [Examples](#examples-2)
-  - [expandPropertyShorthand(property: string, value: string, [recursivelyResolve=false]): Object](#expandpropertyshorthandproperty-string-value-string-recursivelyresolvefalse-object)
+  - [expandShorthandProperty(property: string, value: string, [recursivelyResolve=false]): Object](#expandshorthandpropertyproperty-string-value-string-recursivelyresolvetrue-object)
       - [Examples](#examples-3)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -74,15 +74,15 @@ console.log(getShorthandComputedProperties('unknown'))
 
 // expandShorthandProperty
 // returns an obejct mapping longhand property names to their values
-console.log(expandPropertyShorthand('margin', '0 3px 10rem'))
+console.log(expandShorthandProperty('margin', '0 3px 10rem'))
 // => {
 //      'margin-top': '0',
 //      'margin-right': '3px',
 //      'margin-bottom': '10rem',
 //      'margin-left': '3px',
 //     }
 
-console.log(expandPropertyShorthand('background', 'fixed padding-box url(image.png) rgb(255, 255, 0) 10px top / cover repeat-x'))
+console.log(expandShorthandProperty('background', 'fixed padding-box url(image.png) rgb(255, 255, 0) 10px top / cover repeat-x'))
 // => {
 //      'background-attachment': 'fixed',
 //      'background-clip': 'padding-box',
@@ -222,7 +222,7 @@ Currently supports the following properties:
 ##### Examples
 
 ```js
-expandPropertyShorthand('margin', '0 3px 10rem')
+expandShorthandProperty('margin', '0 3px 10rem')
 // => {
 //      'margin-top': '0',
 //      'margin-right': '3px',
@@ -232,7 +232,7 @@ expandPropertyShorthand('margin', '0 3px 10rem')
 ```
 
 ```js
-expandPropertyShorthand('flex', 'initial')
+expandShorthandProperty('flex', 'initial')
 // => {
 //  'flex-grow': 'initial',
 //  'flex-shrink': 'initial',
@@ -241,11 +241,24 @@ expandPropertyShorthand('flex', 'initial')
 ```
 
 ```js
-expandPropertyShorthand('border-radius', '10px 5px 2em / 20px 25px 30%')
+expandShorthandProperty('border-radius', '10px 5px 2em / 20px 25px 30%')
 // => {
 //   'border-top-left-radius': '10px / 20px',
 //   'border-top-right-radius': '5px / 25px',
 //   'border-bottom-left-radius': '5px / 25px',
 //   'border-bottom-right-radius': '2em / 30%',
 // }
 ```
+
+### Developer/Contribution HOWTO
+
+To use a locally-built version of `css-values-parser`:
+
+```
+$ npm install
+$ npm run start
+$ npm test
+```
+
+This will generate grammars and javascript code required to parse the
+css properties.

css-property-parser.d.ts

@@ -0,0 +1,60 @@
+export = CssPropertyParser;
+
+declare namespace CssPropertyParser {
+  interface Declarations {
+    [property: string]: string;
+  }
+
+  /**
+   * 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
+   * is not a shorthand property) simply returns an object mapping the original property to the original value.
+   *
+   * @param {string} propertyName - the property name for the given value
+   * @param {string} propertyValue - the value of the property
+   * @param {boolean} [recursivelyResolve=true] - 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.
+   */
+  function expandShorthandProperty(
+    propertyName: string,
+    propertyValue: string,
+    recursivelyResolve?: boolean
+  ): Declarations;
+
+ /**
+  * Given a shorthand property, returns an array of the computed properties for that shorthand property. If given
+  * a known property that is not a shorthand, simply returns the given property. If given an unknown property,
+  * returns an empty array.
+  *
+  * @param {string} shorthandProperty - the shorthand property name. For example, "background" or "border".
+  * @returns {Array} - an array containing the computed properties for the given shorthand property. Returns an
+  *                    empty array if the given property is not a valid property.
+  */
+  function getShorthandComputedProperties(
+    shorthandProperty: string
+  ): Array<string>;
+
+  /**
+   * Checks if a given property is a shorthand property
+   * @param {String} property - the property name
+   * @returns {boolean} - true if property is a shorthand, false otherwise
+   */
+  function isShorthandProperty(
+    shorthandProperty: string
+  ): boolean;
+
+  /**
+   * Checks if the given property, value pair is valid.
+   *
+   * @param {String} property - the property name. For example, 'border' or 'color'.
+   * @param {String} value - the property value. For example, '1px solid black'.
+   * @return {boolean} - true if the given value is valid for the property. Else, false.
+   */
+  function isValidDeclaration(
+    property: string,
+    value: string
+  ): boolean;
+
+}

package.json

@@ -2,10 +2,10 @@
   "name": "css-property-parser",
   "version": "1.0.0",
   "description": "Validate css properties and expand shorthand css properties",
-  "main": "index.js",
+  "main": "src/index.js",
   "scripts": {
     "test": "./node_modules/.bin/mocha --reporter spec --recursive",
-    "start": "mkdir -p src/grammars/generated/json && node ./node_modules/nearley/bin/nearleyc.js ./src/grammars/nearley/formalSyntax.ne > ./src/grammars/js/formalSyntax.js && node ./src/scripts/updateBasicDataUnits.js && node ./src/scripts/formatData.js && node ./src/scripts/formatFormalSyntaxes.js && node ./src/scripts/formatGrammars.js",
+    "start": "mkdir -p formatted-data src/grammars/generated/json && node ./node_modules/nearley/bin/nearleyc.js ./src/grammars/nearley/formalSyntax.ne > ./src/grammars/js/formalSyntax.js && node ./src/scripts/updateBasicDataUnits.js && node ./src/scripts/formatData.js && node ./src/scripts/formatFormalSyntaxes.js && node ./src/scripts/formatGrammars.js",
     "clean": "rm -rf src/grammars/generated",
     "benchmark": "node test/benchmark.js",
     "doctoc": "node ./node_modules/doctoc/doctoc.js README.md",
@@ -15,6 +15,7 @@
   "pre-commit": [ "precommit-msg", "lint", "test"],
   "author": "mahirshah",
   "license": "ISC",
+  "types": "css-property-parser.d.ts",
   "devDependencies": {
     "async": "^2.5.0",
     "benchmark": "^2.1.4",
@@ -29,13 +30,13 @@
     "microtime": "^2.1.6",
     "mocha": "^3.5.0",
     "pre-commit": "^1.2.2",
+    "postcss-value-parser": "^3.3.0",
     "sinon": "^2.4.1"
   },
   "dependencies": {
     "fs-extra": "^3.0.1",
     "mdn-data": "1.0.0",
     "moo": "^0.4.1",
-    "nearley": "^2.10.3",
-    "postcss-value-parser": "^3.3.0"
+    "nearley": "^2.10.3"
   }
 }

src/expandShorthandProperty.js

@@ -50,7 +50,7 @@ const R_BLOCK_COMMENT = /\/\*.*?\*\//g;
  *                                      yet.
  *
  * @example
- * expandPropertyShorthand('margin', '0 3px 10rem')
+ * expandShorthandProperty('margin', '0 3px 10rem')
  *  {
  *    'margin-top': '0',
  *    'margin-right': '3px',
@@ -59,7 +59,7 @@ const R_BLOCK_COMMENT = /\/\*.*?\*\//g;
  *   }
  *
  * @example
- * expandPropertyShorthand('flex', 'initial')
+ * expandShorthandProperty('flex', 'initial')
  * {
  *  'flex-grow': 'initial',
  *  'flex-shrink': 'initial',

src/index.js

@@ -1,10 +1,10 @@
-const expandPropertyShorthand = require('./expandShorthandProperty');
+const expandShorthandProperty = require('./expandShorthandProperty');
 const getShorthandComputedProperties = require('./getShorthandComputedProperties');
 const isShorthandProperty = require('./isShorthandProperty');
 const isValidDeclaration = require('./isValidDeclaration');
 
 module.exports = {
-  expandPropertyShorthand,
+  expandShorthandProperty,
   getShorthandComputedProperties,
   isShorthandProperty,
   isValidDeclaration,