Add expressions to style spec docs

docs/.eslintrc

@@ -1,13 +1,5 @@
 {
-    "parser": "espree",
-    "parserOptions": {
-        "ecmaVersion": 5
-    },
-    "env": {
-        "es6": false,
-        "browser": true
-    },
-    "globals": {
-        "Uint8Array": true
+    "rules": {
+      "flowtype/require-valid-file-annotation": [0]
     }
 }

docs/_posts/examples/.eslintrc

@@ -1,11 +1,16 @@
 {
+  "parser": "espree",
+  "parserOptions": {
+      "ecmaVersion": 5
+  },
   "plugins": ["html"],
   "globals": {
     "mapboxgl": true,
     "MapboxGeocoder": true,
     "MapboxDirections": true,
     "turf": true,
-    "d3": true
+    "d3": true,
+    "Uint8Array": true
   },
   "rules": {
     "flowtype/require-valid-file-annotation": [0],
@@ -17,6 +22,7 @@
     "prefer-template": "off"
   },
   "env": {
+    "es6": false,
     "browser": true
   }
 }

docs/style-spec/_generate/expression-types.js

@@ -0,0 +1,110 @@
+'use strict';
+require('flow-remove-types/register');
+
+const toString = require('../../../src/style-spec/function/types').toString;
+const CompoundExpression = require('../../../src/style-spec/function/compound_expression').CompoundExpression;
+
+// registers compound expressions
+require('../../../src/style-spec/function/definitions');
+
+const results = {
+    array: [{
+        type: 'Array',
+        parameters: ['Value'],
+    }, {
+        type: 'Array<type>',
+        parameters: [
+            {name: 'type', type: '"String" | "Number" | "Boolean"'},
+            'Value'
+        ],
+    }, {
+        type: 'Array<type, N>',
+        parameters: [
+            {name: 'type', type: '"String" | "Number" | "Boolean"'},
+            {name: 'N', type: 'Number (literal)'},
+            'Value'
+        ]
+    }],
+    at: [{
+        type: 'T',
+        parameters: ['Number', 'Array']
+    }],
+    case: [{
+        type: 'T',
+        parameters: [{ repeat: ['Boolean', 'T'] }, 'T']
+    }],
+    coalesce: [{
+        type: 'T',
+        parameters: [{repeat: 'T'}]
+    }],
+    contains: [{
+        type: 'Boolean',
+        parameters: ['T', 'Array<T> | Array<T, N>']
+    }],
+    curve: [{
+        type: 'T',
+        parameters: [
+            {name: 'input', type: 'Number'},
+            '["step"]',
+            'T',
+            {repeat: ['Number', 'T']}
+        ]
+    }, {
+        type: 'T: Number, ',
+        parameters: [
+            {name: 'input', type: 'Number'},
+            {name: 'interpolation', type: '["step"] | ["linear"] | ["exponential", base] | ["cubic-bezier", x1, y1, x2, y2 ]'},
+            {repeat: ['Number', 'T']}
+        ]
+    }],
+    let: [{
+        type: 'T',
+        parameters: [{ repeat: ['String (alphanumeric literal)', 'any']}, 'T']
+    }],
+    literal: [{
+        type: 'Array<T, N>',
+        parameters: ['[...] (JSON array literal)']
+    }, {
+        type: 'Object',
+        parameters: ['{...} (JSON object literal)']
+    }],
+    match: [{
+        type: 'U',
+        parameters: [
+            {name: 'input', type: 'T: Number (integer literal) | String (literal)'},
+            {repeat: ['T | [T, T, ...]', 'U']},
+            'U'
+        ]
+    }],
+    var: [{
+        type: 'the type of the bound expression',
+        parameters: ['previously bound variable name']
+    }]
+};
+
+for (const name in CompoundExpression.definitions) {
+    const definition = CompoundExpression.definitions[name];
+    if (Array.isArray(definition)) {
+        results[name] = [{
+            type: toString(definition[0]),
+            parameters: processParameters(definition[1])
+        }];
+    } else {
+        results[name] = definition.overloads.map((o) => {
+            return {
+                type: toString(definition.type),
+                parameters: processParameters(o[0])
+            };
+        });
+    }
+}
+
+function processParameters(params) {
+    if (Array.isArray(params)) {
+        return params.map(toString);
+    } else {
+        return [{repeat: [toString(params.type)]}];
+    }
+}
+
+module.exports = results;

docs/style-spec/_generate/expression.html

@@ -0,0 +1,12 @@
+<div class='col12 clearfix pad0y pad2x space-top0'>
+  <span class='space-right'>
+    <%= md("<a class='code' id='types-expression-" + name + "' href='#types-expression-" + name + "'>" + name + "</a> " + (expressionDocs[name] ? ('<br>' + expressionDocs[name].doc) : '').trim()) %>
+  </span>
+  <% for (const overload of expressionTypes[name]) { %>
+    <div>
+{% highlight javascript %}
+<%=renderSignature(name, overload) %>
+{% endhighlight %}
+</div>
+  <% } %>
+</div>

docs/style-spec/_generate/generate.js

@@ -9,8 +9,11 @@ var _ = require('lodash');
 var remark = require('remark');
 var html = require('remark-html');
 
+var expressionTypes = require('./expression-types');
+
+
 function tmpl(x, options) {
-  return _.template(fs.readFileSync(path.join(__dirname, x), 'utf-8'), options);
+    return _.template(fs.readFileSync(path.join(__dirname, x), 'utf-8'), options);
 }
 
 var index = tmpl('index.html', {
@@ -23,8 +26,47 @@ var index = tmpl('index.html', {
           return remark().use(html).process(markdown);
         }
       }
+    }),
+    expressions: Object.keys(expressionTypes).sort((a, b) => a.localeCompare(b)),
+    renderExpression: tmpl('expression.html', {
+      imports: {
+        _: _,
+        expressionDocs: ref['expression_name'].values,
+        expressionTypes: expressionTypes,
+        renderSignature: renderSignature,
+        md: function(markdown) {
+          return remark().use(html).process(markdown)
+        }
+      }
     })
   }
 });
 
+function renderSignature (name, overload) {
+    name = JSON.stringify(name);
+    const maxLength = 80 - name.length - overload.type.length;
+    const params = renderParams(overload.parameters, maxLength);
+    return `[${name}${params}]: ${overload.type}`;
+}
+
+function renderParams (params, maxLength) {
+    const result = [''];
+    for (const t of params) {
+        if (typeof t === 'string') {
+            result.push(t);
+        } else if (t.name) {
+            result.push(`${t.name}: ${t.type}`);
+        } else if (t.repeat) {
+            const repeated = renderParams(t.repeat, Infinity);
+            result.push(`${repeated.slice(2)}${repeated}, ...`);
+        }
+    }
+
+    // length of result = each (', ' + item)
+    const length = result.reduce((l, s) => l + s.length + 2, 0);
+    return (!maxLength || length <= maxLength) ?
+        result.join(', ') :
+        `${result.join(',\n    ')}\n`;
+}
+
 fs.writeFileSync(path.join(__dirname, '../index.html'), index({ ref: ref }));