├── .gitignore
├── .npmignore
├── LICENSE
├── README.md
├── package.json
├── rollup.config.js
└── src
    └── index.js


/.gitignore:
--------------------------------------------------------------------------------
1 | dist/
2 | node_modules/


--------------------------------------------------------------------------------
/.npmignore:
--------------------------------------------------------------------------------
1 | node_modules/


--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
 1 | MIT License
 2 | 
 3 | Copyright (c) 2019 Graham McNeill
 4 | 
 5 | Permission is hereby granted, free of charge, to any person obtaining a copy
 6 | of this software and associated documentation files (the "Software"), to deal
 7 | in the Software without restriction, including without limitation the rights
 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 | 
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 | 
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | ---
  2 | 
  3 | __Note:__ Vega-Lite now has its own [JavaScript API](https://github.com/vega/vega-lite-api/) so Vizsla is no longer in active development.
  4 | 
  5 | ---
  6 | 
  7 | Vizsla is a simple JavaScript API for [Vega-Lite](https://vega.github.io/vega-lite/):
  8 | 
  9 | ```js
 10 | //scatter plot
 11 | vz(cars)
 12 |   .x('Horsepower')
 13 |   .y('Miles_per_Gallon')
 14 |   .plot()
 15 | ```
 16 | 
 17 | See this [Observable notebook](https://beta.observablehq.com/@gjmcn/vizsla-and-vega-lite) for some interactive examples.
 18 | 
 19 | ## Install/Load
 20 | 
 21 | Vizsla uses the Universal Module Definition (UMD) so should work in any JavaScript environment. For example:
 22 | 
 23 | * Node.js:
 24 | 	* install: `npm install --save @gjmcn/vizsla`
 25 | 	* load: `const vz = require('@gjmcn/vizsla');`
 26 | 
 27 | * Browser, using `<script>`: creates a global variable `vz`
 28 | 
 29 | ## API Reference
 30 | 
 31 | ### Constructors
 32 | 
 33 | * Except for `vz.Vizsla`, do not use `new` when calling constructors.
 34 | 
 35 | * Constructors can be called with no arguments. For example, `vz.repeat()` creates a repeat spec with no inner spec; use [inner](#method_inner) to set the inner spec.
 36 | 
 37 | ---
 38 | 
 39 | <a name="method_vz" href="#method_vz">#</a> `vz(d, ops)`
 40 | 
 41 | &emsp;&emsp;`d`: string (URL of data) or object/array (data)
 42 | 
 43 | &emsp;&emsp;`ops`: options object
 44 | 
 45 | Creates a unit spec and, if `d` is truthy, sets its data &mdash; see [data](#method_data).
 46 | 
 47 | Unit specs have mark type `'point'` by default.
 48 | 
 49 | Returns a new unit spec.
 50 | 
 51 | ---
 52 | 
 53 | <a name="method_layer" href="#method_layer">#</a> `vz.layer(sub0, sub1, sub2, ...)`
 54 | 
 55 | &emsp;&emsp;`sub0`, `sub1`, `sub2`, ... : specs to be layered; unit and layer specs only
 56 | 
 57 | Returns a new layer spec.
 58 | 
 59 | ---
 60 | 
 61 | <a name="method_hconcat" href="#method_hconcat">#</a> `vz.hconcat(sub0, sub1, sub2, ...)`<br>
 62 | <a name="method_vconcat" href="#method_vconcat">#</a> `vz.vconcat(sub0, sub1, sub2, ...)`
 63 | 
 64 | &emsp;&emsp;`sub0`, `sub1`, `sub2`, ... : specs to be concatenated
 65 | 
 66 | Returns a new hconcat or vconcat spec.
 67 | 
 68 | ---
 69 | 
 70 | <a name="method_facet" href="#method_facet">#</a> `vz.facet(sub)`
 71 | 
 72 | &emsp;&emsp;`sub`: spec to be faceted
 73 | 
 74 | Use `row` and `column` (see [encode](#method_encode)) to set the channels.
 75 | 
 76 | Use [data](#method_data) to set the data property of a facet. If a facet does not have a data property, it uses the data of the first unit in its inner spec that has a data property &mdash; all units in the inner spec that use this data ignore their own data property.
 77 | 
 78 | Note: nested facets are not currently supported in Vizsla.
 79 | 
 80 | Returns a new facet spec.
 81 | 
 82 | ---
 83 | 
 84 | <a name="method_repeat" href="#method_repeat">#</a> `vz.repeat(sub)`
 85 | 
 86 | &emsp;&emsp;`sub`: spec to be repeated
 87 | 
 88 | Use [across](#method_across) and [down](#method_down) to set the repeat directions and channels.
 89 | 
 90 | Note: Vizsla currently only allows a unit or facet spec to be repeated.
 91 | 
 92 | Returns a new repeat spec.
 93 | 
 94 | ---
 95 | 
 96 | <a name="method_vizsla" href="#method_vizsla">#</a> `vz.Vizsla(type = 'unit')`
 97 | 
 98 | &emsp;&emsp;type: string, `'unit'`, `'layer'`, `'hconcat'`, `'vconcat'`, `'facet'` or `'repeat'`
 99 | 
100 | `vz.Vizsla` is a standard constructor, so e.g. `new vz.Vizsla()` returns a new unit spec.
101 | 
102 | ---
103 | 
104 | ### Methods
105 | 
106 | * The following 'spec' methods are actually methods of `vz.Vizsla.prototype`.
107 | 
108 | * Various methods accept an 'options object' as their final argument. This is used to specify properties which are not covered by a dedicated method or argument. For example:
109 | 
110 |   ```js
111 |   vz(cars)
112 |     .bar()
113 |     .x('Cylinders', 'o')
114 |     .y('Acceleration', 'q', {aggregate: 'mean'})  //options object
115 |     .plot();
116 |   ```
117 | 
118 | ---
119 | 
120 | <a name="method_mark" href="#method_mark">#</a> `spec.mark(type, ops)`
121 | 
122 | &emsp;&emsp;spec type: unit
123 | 
124 | &emsp;&emsp;`type`: string, the mark type
125 | 
126 | &emsp;&emsp;`ops`: options object
127 | 
128 | Set mark: type to `type` plus any additional mark properties specified in `ops`.
129 | 
130 | There are also convenience mark methods:
131 | 
132 | `area`, `bar`, `boxplot`, `circle`, `errorband`, `errorbar`, `geoshape`, `line`, `point`, `rect`, `rule`, `square`, `text`, `tick`, `trail`
133 | 
134 | ```js
135 | //these are equivalent
136 | vz().bar();
137 | vz().mark('bar');
138 | 
139 | //these are equivalent
140 | vz().bar(ops);
141 | vz().mark('bar', ops);
142 | ```
143 | 
144 | Mark methods return the spec.
145 | 
146 | ---
147 | 
148 | <a name="method_encode" href="#method_encode">#</a> `spec.encode(chn, field, type = 'q', ops)`
149 | 
150 | &emsp;&emsp;spec type: unit, layer, facet
151 | 
152 | &emsp;&emsp;`chn`: string, channel name
153 | 
154 | &emsp;&emsp;`field`: string, field name
155 | 
156 | &emsp;&emsp;`type`: string, `'q'`, `'quantitative'`, `'t'`, `'temporal'`, `'o'`, `'ordinal'`, `'n'` or `'nominal'`
157 | 
158 | &emsp;&emsp;`ops`: options object
159 | 
160 | Set channel `chn`: field to `field`, type to `type` plus any additional properties specified in `ops`.
161 | 
162 | There are also convenience methods:
163 | 
164 | `x`, `y`, `x2`, `y2`, `longitude`, `latitude`, `longitude2`, `latitude2`,
165 | `color`, `opacity`, `fillOpacity`, `strokeOpacity`, `strokeWidth`, `size`,
166 | `shape`, `label`, `tooltip`, `href`, `key`, `order`, `detail`, `row`, `column`
167 | 
168 | ```js
169 | //these are equivalent
170 | vz(cars).x('Horsepower');
171 | vz(cars).encode('x', 'Horsepower');
172 | 
173 | //these are equivalent
174 | vz(cars).x('Horsepower', 'q', ops);
175 | vz(cars).encode('x', 'Horsepower', 'q', ops);
176 | ```
177 | 
178 | The `label` method actually corresponds to the text channel &mdash; `text` is a mark method.
179 | 
180 | Pass a non-`null` falsy value as `field` to omit the field property from the channel object.
181 | 
182 | Pass `true` as `field` as a shortcut for the count aggregate:
183 | 
184 | ```js
185 | //these are equivalent
186 | vz().y(true);
187 | vz().y(false, 'q', {aggregate: 'count'});
188 | 
189 | //these are equivalent
190 | vz().y(true, 'q', {title: 'Total'});
191 | vz().y(false, 'q', {aggregate: 'count', title: 'Total'});
192 | ```
193 | 
194 | These methods return the spec.
195 | 
196 | ---
197 | 
198 | <a name="method_transform" href="#method_transform">#</a> `spec.transform(t0, t1, t2, ...)`
199 | 
200 | &emsp;&emsp;spec type: any
201 | 
202 | &emsp;&emsp;`t0`, `t1`, `t2`, ... : object
203 | 
204 | Set transform.
205 | 
206 | Returns the spec.
207 | 
208 | ---
209 | 
210 | <a name="method_projection" href="#method_projection">#</a> `spec.projection(type = 'mercator', ops)`
211 | 
212 | &emsp;&emsp;spec type: unit, layer
213 | 
214 | &emsp;&emsp;type: string
215 | 
216 | &emsp;&emsp;`ops`: options object
217 | 
218 | Set projection: type to `type` plus any additional properties specified in `ops`.
219 | 
220 | Returns the spec.
221 | 
222 | ---
223 | 
224 | <a name="method_across" href="#method_across">#</a> `spec.across(chn, fields = [])`<br>
225 | <a name="method_down" href="#method_down">#</a> `spec.down(chn, fields = [])`
226 | 
227 | &emsp;&emsp;spec type: repeat
228 | 
229 | &emsp;&emsp;`chn`: string, channel name
230 | 
231 | &emsp;&emsp;`fields`: array of strings, field names
232 | 
233 | Set across/down repeat to use channel `chn` and fields `fields`.
234 | 
235 | ---
236 | 
237 | <a name="method_data" href="#method_data">#</a> `spec.data(d, ops)`
238 | 
239 | &emsp;&emsp;spec type: unit, facet
240 | 
241 | &emsp;&emsp;`d`: string (URL of data) or object/array (data)
242 | 
243 | &emsp;&emsp;`ops`: options object
244 | 
245 | Set data: url/values to `d` plus any additional properties specified in `ops`.
246 | 
247 | Note: only unit and facet specs can have data in Vizsla.
248 | 
249 | Returns the spec.
250 | 
251 | ---
252 | 
253 | <a name="method_inner" href="#method_inner">#</a> `spec.inner(sub0, sub1, sub2, ...)`
254 | 
255 | &emsp;&emsp;spec type: layer, hconcat, vconcat, facet, repeat
256 | 
257 | &emsp;&emsp; `sub0`, `sub1`, `sub2`, ... : spec object
258 | 
259 | Set inner spec(s) to `sub0`, `sub1`, `sub2`, ... 
260 | 
261 | Returns the spec.
262 | 
263 | ---
264 | 
265 | The following methods set the property of the same name to the argument and return the spec.
266 | 
267 | | Name | Spec type |
268 | | ---- | --------- |
269 | | <code>description(<i>string</i>)</code> | any |
270 | | <code>title(<i>string</i>)</code> | any |
271 | | <code>name(<i>string</i>)</code> | any (only used at top-level)|
272 | | <code>$schema(<i>string</i>)</code> | any (only used at top-level) |
273 | | <code>background(<i>string</i>)</code> | any (only used at top-level) |
274 | | <code>padding(<i>number/object</i>)</code> | any (only used at top-level) |
275 | | <code>autosize(<i>string/object</i>)</code> | any (only used at top-level) |
276 | | <code>config(<i>object</i>)</code> | any (only used at top-level) |
277 | | <code>resolve(<i>object</i>)</code> | layer, hconcat, vconcat, facet, repeat |
278 | | <code>center(<i>boolean/object</i>)</code> | hconcat, vconcat, facet, repeat |
279 | | <code>spacing(<i>number/object</i>)</code> | hconcat, vconcat, facet, repeat |
280 | | <code>bounds(<i>string</i>)</code> | hconcat, vconcat, facet, repeat |
281 | | <code>align(<i>string/object</i>)</code> | facet, repeat |
282 | | <code>width(<i>number</i>)</code> | unit, layer |
283 | | <code>height(<i>number</i>)</code> | unit, layer |
284 | | <code>selection(<i>object</i>)</code> | unit |
285 | 
286 | Example: 
287 | 
288 | ```js
289 | vz()
290 |   .width(300)
291 |   .height(200);
292 | ```
293 | 
294 | ---
295 | 
296 | <a name="method_copy" href="#method_copy">#</a> `spec.copy(recursive = true)`
297 | 
298 | Copy spec. All properties are deep copied except that:
299 | 
300 | * If `recursive` is falsy, the inner spec(s) are not included in the copy.
301 | 
302 | * Inline data is _not_ copied. Specifically, the data object is deep copied except for its `values` property &mdash; the spec and the copy refer to the same data structure.
303 | 
304 | Returns the copy.
305 | 
306 | ---
307 | 
308 | <a name="method_prep" href="#method_prep">#</a> `spec.prep()`
309 | 
310 | Returns a Vega-Lite spec object ready to be rendered. The returned spec is independent of the calling spec with the possible exception that they share inline data (since Vizsla does not copy inline data).
311 | 
312 | The returned spec uses the Vega-Lite `datasets` property to avoid repeating inline data and for repeat specs, includes appropriately modified versions of the inner specs.
313 | 
314 | ---
315 | 
316 | <a name="method_plot" href="#method_plot">#</a> `vz.Vizsla.prototype.plot()`
317 | 
318 | The `plot` property is initially `undefined`. It should be set to a function that renders the spec.
319 | 
320 | [Vega-Embed](https://github.com/vega/vega-embed) examples:
321 | 
322 | * use Vizsla in an HTML document where Vega-Embed is loaded in a `<script>` tag:
323 | 
324 |   ```js
325 |   vz.Vizsla.prototype.plot = function(elm, opt) {
326 |     return vegaEmbed(elm, this.prep(), opt);
327 |   };
328 |   ```
329 | 
330 | * use Vizsla in an [Observable notebook](https://beta.observablehq.com/):
331 | 
332 |   ```js
333 |   //in one cell
334 |   vegaEmbed = require("vega-embed@3")
335 | 
336 |   //in another cell
337 |   vz = {
338 |     const vz = await require('@gjmcn/vizsla');
339 |     vz.Vizsla.prototype.plot = function(opt) {
340 |       return vegaEmbed(this.prep(), opt);
341 |     };
342 |     return vz;
343 |   }
344 |   ```
345 | ---
346 | 
347 | ### Notes
348 | 
349 | * Options arguments (`ops`) take precedence over other arguments and method names. For example, `vz().bar({type: 'line'})` will set the mark type to `'line'`, not `'bar'`.
350 | 
351 | * Pass `null` to delete a spec property:
352 | 
353 |   * `encode` method: `spec.encode('x', null)`
354 | 
355 |   * other methods: pass `null` as the first argument; e.g. `spec.x(null)` or `spec.mark(null)` or `spec.inner(null)`
356 | 
357 | * Spec objects have the structure:
358 | 
359 |   ```
360 |   object
361 |     spec           //object, spec manipulated by vz methods
362 |     type           //string, spec type
363 |     use            //object (unit specs only), data
364 |     repeatChannel  //object (repeat spec only), repeat channel(s)
365 |   ```
366 | 
367 | ## Contributions
368 | 
369 | Are welcome! Open an issue or create a pull request.
370 | 
371 | ## Also See
372 | 
373 | * [Altair](https://github.com/altair-viz/altair) &mdash; Python
374 | * [VegaLite.jl](https://github.com/fredo-dedup/VegaLite.jl) &mdash; Julia
375 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "@gjmcn/vizsla",
 3 |   "version": "0.1.1",
 4 |   "description": "A simple JavaScript API for Vega-Lite.",
 5 |   "main": "dist/index.js",
 6 |   "scripts": {
 7 |     "test": "echo \"Error: no test specified\" && exit 1",
 8 |     "build": "rollup -c"
 9 |   },
10 |   "repository": {
11 |     "type": "git",
12 |     "url": "git+https://github.com/gjmcn/vizsla.git"
13 |   },
14 |   "author": "Graham McNeill",
15 |   "license": "MIT",
16 |   "bugs": {
17 |     "url": "https://github.com/gjmcn/vizsla/issues"
18 |   },
19 |   "homepage": "https://github.com/gjmcn/vizsla#readme",
20 |   "devDependencies": {
21 |     "rollup": "^0.59.1",
22 |     "rollup-plugin-commonjs": "^9.1.0",
23 |     "rollup-plugin-node-resolve": "^3.3.0",
24 |     "rollup-plugin-uglify": "^3.0.0"
25 |   },
26 |   "dependencies": {
27 |     "clone": "^2.1.2"
28 |   }
29 | }
30 | 


--------------------------------------------------------------------------------
/rollup.config.js:
--------------------------------------------------------------------------------
 1 | import commonjs from 'rollup-plugin-commonjs';
 2 | import resolve from 'rollup-plugin-node-resolve';
 3 | import uglify from 'rollup-plugin-uglify';
 4 | 
 5 | export default {
 6 |   input: 'src/index',
 7 |   output: {
 8 |     extend: true,
 9 |     file: 'dist/index.js',
10 |     format: 'umd',
11 |     name: 'vz'
12 |   },
13 |   plugins: [
14 |     commonjs({
15 |       sourceMap: false
16 |     }),
17 |     resolve(),
18 |     uglify()
19 |   ]
20 | };


--------------------------------------------------------------------------------
/src/index.js:
--------------------------------------------------------------------------------
  1 | (() => {
  2 |   
  3 |   'use strict';
  4 | 
  5 | 
  6 |   //---------- copy functions ----------
  7 | 
  8 |   const clone = require('clone');
  9 | 
 10 |   const copyDataObject = (d, name) => {
 11 |     const c = {};
 12 |     for (let prop in d) {
 13 |       if (prop === 'values') {
 14 |         if (name) c.name = name;
 15 |         else c.values = d.values;  //not copied
 16 |       }
 17 |       else c[prop] = clone(d[prop]);
 18 |     }
 19 |     return c;
 20 |   };
 21 | 
 22 | 
 23 |   //---------- assert ----------
 24 | 
 25 |   const assert = {
 26 |     typeof(x, type) {
 27 |       if (typeof x !== type) throw Error(type + ' expected');
 28 |     },
 29 |     array(a) {
 30 |       if (!Array.isArray(a)) throw Error('array expected');
 31 |     },
 32 |     Vizsla(obj) {
 33 |       if (!(obj instanceof Vizsla)) throw Error('Vizsla object expected');
 34 |     }
 35 |   };
 36 | 
 37 | 
 38 |   //---------- constructors ----------
 39 |   
 40 |   let Vizsla, vz;
 41 |   {
 42 | 
 43 |     const types = new Set([
 44 |       'unit', 'layer', 'hconcat', 'vconcat', 'facet', 'repeat'
 45 |     ]);
 46 | 
 47 |     //constructor
 48 |     Vizsla = function(type = 'unit') {
 49 |       if (!types.has(type)) throw Error('invalid spec type');
 50 |       this.type = type;
 51 |       this.spec = { $schema: 'https://vega.github.io/schema/vega-lite/v3.json' };
 52 |       if (type === 'unit') {
 53 |         this.spec.encoding = {};
 54 |         this.spec.mark = { type: 'point' };
 55 |       }
 56 |       else if (type === 'layer') this.spec.encoding = {};
 57 |       else if (type === 'facet') this.spec.facet = {};
 58 |       else if (type === 'repeat') {
 59 |         this.spec.repeat = {};
 60 |         this.repeatChannel = {};
 61 |       }
 62 |     };
 63 | 
 64 |     //unit
 65 |     vz = function(d, ops) {
 66 |       const vizObj = new Vizsla('unit');
 67 |       if (d) vizObj.data(d, ops);
 68 |       return vizObj;
 69 |     };
 70 | 
 71 |     //composition
 72 |     for (let name of ['layer', 'hconcat', 'vconcat', 'facet', 'repeat']) {
 73 |       vz[name] = (...sub) => {
 74 |         const vizObj = new Vizsla(name);
 75 |         if (sub.length) vizObj.inner(...sub);
 76 |         return vizObj;
 77 |       };
 78 |     }
 79 | 
 80 |     //include constructor in vz
 81 |     vz.Vizsla = Vizsla;
 82 | 
 83 |   }
 84 | 
 85 | 
 86 |   //---------- methods ----------
 87 | 
 88 |   //data
 89 |   Vizsla.prototype.data = function(d, ops) {
 90 |     if (this.type !== 'unit' && this.type !== 'facet') {
 91 |       throw Error('unit or facet spec expected');
 92 |     }
 93 |     if (d === null) delete this.use;
 94 |     else {
 95 |       let data;
 96 |       if (typeof d === 'string') data = { url: d };
 97 |       else if (typeof d === 'object') data = { values: d };
 98 |       else throw Error('invalid data');       
 99 |       if (ops) Object.assign(data, ops);
100 |       this.use = data;
101 |     }
102 |     return this;
103 |   };
104 | 
105 |   //inner
106 |   Vizsla.prototype.inner = function(...sub) {
107 |     if (this.type === 'unit') throw Error('composition spec expected');
108 |     const facetOrRepeat = (this.type === 'facet' || this.type === 'repeat');
109 |     if (sub[0] === null) delete this.spec[facetOrRepeat ? 'spec' : this.type];
110 |     else {
111 |       for (let s of sub) assert.Vizsla(s);
112 |       if (facetOrRepeat) {
113 |         if (sub.length) {
114 |           if (this.type === 'repeat' && 
115 |               sub[0].type !== 'unit' && sub[0].type !== 'facet') {
116 |             throw Error('Vizsla currently only supports repeating a unit or facet');
117 |           } 
118 |           this.spec.spec = sub[0];
119 |         }
120 |         else delete this.spec.spec;
121 |       }
122 |       else {  //layer, hconcat or vconcat
123 |         if (this.type === 'layer') {
124 |           for (let s of sub) {
125 |             if (s.type !== 'unit' && s.type !== 'layer') {
126 |               throw Error('inner specs of layer must be units or layers');
127 |             } 
128 |           }
129 |         }
130 |         this.spec[this.type] = sub;
131 |       }
132 |     }
133 |     return this;
134 |   };
135 | 
136 |   //mark
137 |   {
138 |     
139 |     //valid marks
140 |     const marks = new Set([
141 |       'area', 'bar', 'boxplot', 'circle', 'errorband', 'errorbar', 'geoshape',
142 |       'line', 'point', 'rect', 'rule', 'square', 'text', 'tick', 'trail'
143 |     ]);
144 |     
145 |     //main mark method
146 |     Vizsla.prototype.mark = function(type, ops) {
147 |       if (this.type !== 'unit') throw Error('unit spec expected');
148 |       if (type === null) delete this.spec.mark;
149 |       else {
150 |         if (!marks.has(type)) throw Error('invalid mark type');
151 |         const obj = { type };
152 |         if (ops) Object.assign(obj, ops);
153 |         this.spec.mark = obj;
154 |       }
155 |       return this;
156 |     }
157 | 
158 |     //convenience mark methods
159 |     for (let m of marks) {
160 |       Vizsla.prototype[m] = function(ops) {
161 |         this.mark(m, ops);
162 |         return this;
163 |       };
164 |     }
165 | 
166 |   }
167 | 
168 |   //channels, including across and down methods for repeat
169 |   {
170 | 
171 |     const types = new Set([
172 |       'nominal', 'ordinal', 'quantitative', 'temporal', 'geojson'
173 |     ]);
174 | 
175 |     const typeLookup = {};
176 |     for (let t of types) typeLookup[t[0]] = t;
177 | 
178 |     const expandType = t => {
179 |       t = '' + t;
180 |       if (t.length === 1) t = typeLookup[t];
181 |       if (!types.has(t)) throw Error('invalid data type');
182 |       return t;
183 |     };
184 | 
185 |     //valid channels
186 |     const channels = new Set([
187 |       'x', 'y', 'x2', 'y2', 'longitude', 'latitude', 'longitude2', 'latitude2',
188 |       'color', 'opacity', 'fillOpacity', 'strokeOpacity', 'strokeWidth', 'size',
189 |       'shape', 'label', 'tooltip', 'href', 'key', 'order', 'detail', 'row', 'column'
190 |     ]);
191 | 
192 |     const validSpecTypes = new Set(['unit', 'layer', 'facet']);
193 | 
194 |     //encode
195 |     Vizsla.prototype.encode = function(chn, field, type = 'q', ops) {
196 |       if (!validSpecTypes.has(this.type)) {
197 |         throw Error(`${this.type} spec cannot have channels`);
198 |       }
199 |       if (!channels.has(chn)) throw Error('invalid channel');
200 |       if (this.type === 'facet' && chn !== 'row' && chn !== 'column') {
201 |         throw Error('only row and column channels can be used in a facet spec');
202 |       }
203 |       if (chn === 'label') chn = 'text';
204 |       const prop = (this.type === 'facet' ? 'facet' : 'encoding');
205 |       if (field === null) delete this.spec[prop][chn];
206 |       else {
207 |         const obj = {};
208 |         if (field === true) obj.aggregate = 'count';
209 |         else if (field) {
210 |           assert.typeof(field, 'string');
211 |           obj.field = field;
212 |         }
213 |         obj.type = expandType(type);
214 |         if (ops) Object.assign(obj, ops);
215 |         this.spec[prop][chn] = obj;
216 |       }
217 |       return this;
218 |     };
219 | 
220 |     //convenience channel methods
221 |     for (let c of channels) {
222 |       Vizsla.prototype[c] = function(field, type, ops) {
223 |         this.encode(c, field, type, ops);
224 |         return this;
225 |       };
226 |     }
227 | 
228 |     //across, down
229 |     for (let name of ['across', 'down']) {
230 |       const prop = (name === 'across' ? 'column' : 'row');
231 |       Vizsla.prototype[name] = function(chn, fields = []) {
232 |         if (this.type !== 'repeat') throw Error('repeat spec expected');
233 |         if (chn === null) {
234 |           delete this.spec.repeat[prop];
235 |           delete this.repeatChannel[prop];
236 |         }
237 |         else {
238 |           if (!channels.has(chn)) throw Error('invalid channel');
239 |           assert.array(fields);
240 |           for (let f of fields) assert.typeof(f, 'string');
241 |           this.spec.repeat[prop] = fields;
242 |           this.repeatChannel[prop] = chn;
243 |         }
244 |         return this;
245 |       };
246 |     }
247 | 
248 |   }
249 | 
250 |   //transform
251 |   Vizsla.prototype.transform = function(...t) {
252 |     if (t[0] === null) delete this.spec.transform;
253 |     else {
254 |       for (let j of t) assert.typeof(j, 'object');
255 |       this.spec.transform = t;
256 |     }
257 |     return this;
258 |   };
259 | 
260 |   //projection
261 |   Vizsla.prototype.projection = function(type = 'mercator', ops) {
262 |     if (this.type !== 'unit' && this.type !== 'layer') {
263 |       throw Error('unit or layer spec expected');
264 |     }
265 |     if (type === null) delete this.spec.projection;
266 |     else {
267 |       const obj = { type };
268 |       if (ops) Object.assign(obj, ops);
269 |       this.spec.projection = obj;
270 |     }
271 |     return this;
272 |   };
273 | 
274 |   //simple methods
275 |   {
276 | 
277 |     const methods = [];
278 |     const addMethod = (name, type, valid) => {
279 |       methods.push({
280 |         name,
281 |         type: new Set(type),
282 |         valid: valid ? new Set(valid) : null
283 |       });
284 |     };
285 |     addMethod('name',        ['string']);
286 |     addMethod('description', ['string']);
287 |     addMethod('title',       ['string']);
288 |     addMethod('$schema',     ['string']);
289 |     addMethod('background',  ['string']);
290 |     addMethod('padding',     ['number', 'object']);
291 |     addMethod('autosize',    ['string', 'object']);
292 |     addMethod('config',      ['object']);
293 |     addMethod('resolve',     ['object'],            ['layer', 'hconcat', 'vconcat', 'facet', 'repeat']);
294 |     addMethod('center',      ['boolean', 'object'], ['hconcat', 'vconcat', 'facet', 'repeat']);
295 |     addMethod('spacing',     ['number', 'object'],  ['hconcat', 'vconcat', 'facet', 'repeat']);
296 |     addMethod('bounds',      ['string'],            ['hconcat', 'vconcat', 'facet', 'repeat']);
297 |     addMethod('align',       ['string', 'object'],  ['facet', 'repeat']);
298 |     addMethod('width',       ['number'],            ['unit', 'layer']);
299 |     addMethod('height',      ['number'],            ['unit', 'layer']);
300 |     addMethod('selection',   ['object'],            ['unit']);
301 |         
302 |     for (let m of methods) {
303 |       const {name, type, valid} = m;
304 |       Vizsla.prototype[name] = function(val) {
305 |         if (valid && !valid.has(this.type)) {
306 |           throw Error(`${name} cannot be used with a ${this.type} spec`);
307 |         }
308 |         if (val === null) delete this.spec[name];
309 |         else {
310 |           if (!type.has(typeof val)) throw Error('invalid type');
311 |           this.spec[name] = val;
312 |         }
313 |         return this;
314 |       };
315 |     }
316 | 
317 |   }
318 | 
319 |   //copy
320 |   Vizsla.prototype.copy = function(recursive = true) {
321 |     const type = this.type;
322 |     const obj = new Vizsla(type);
323 |     if (this.use) obj.use = copyDataObject(this.use);
324 |     if (this.repeatChannel) obj.repeatChannel = clone(this.repeatChannel);
325 |     if (type === 'unit') obj.spec = clone(this.spec);
326 |     else {
327 |       obj.spec = {};
328 |       if (type === 'facet' || type === 'repeat') {
329 |         for (let prop in this.spec) {
330 |           if (prop === 'spec') {
331 |             if (recursive) obj.spec.spec = this.spec.spec.copy();
332 |           }
333 |           else obj.spec[prop] = clone(this.spec[prop]);
334 |         }
335 |       }
336 |       else {  //layer, hconcat or vconcat
337 |         for (let prop in this.spec) {
338 |           if (prop === type) {
339 |             if (recursive) obj.spec[type] = this.spec[type].map(child => child.copy());
340 |           }
341 |           else obj.spec[prop] = clone(this.spec[prop]);
342 |         }
343 |       }
344 |     }
345 |     return obj;
346 |   };
347 |   
348 |   //prep
349 |   {
350 | 
351 |     const topLevelOnly = ['name', '$schema', 'background', 'padding', 'autosize', 'config'];
352 | 
353 |     const equalDataObjects = (d1, d2) => {
354 |       for (let k of ['url', 'values', 'name']) {
355 |         if (d1[k] && d1[k] === d2[k]) return true;
356 |       }
357 |     };
358 | 
359 |     Vizsla.prototype.prep = function() {
360 |       
361 |       const datasetsMap = new Map();
362 | 
363 |       const finalize = (viz, track, isTopLevel) => {
364 | 
365 |         const final = viz.copy(false).spec;
366 |         const type = viz.type;
367 | 
368 |         if (!isTopLevel) {
369 |           for (let k of topLevelOnly) delete final[k];
370 |         }
371 | 
372 |         //parse data set
373 |         const processData = () => {
374 |           if (viz.use) {
375 |             let dataObj;
376 |             if (viz.use.values) {  //inline data
377 |               let dataName = datasetsMap.get(viz.use.values);
378 |               if (!dataName) {
379 |                 dataName = 'ds_' + datasetsMap.size;
380 |                 datasetsMap.set(viz.use.values, dataName);
381 |               }
382 |               dataObj = copyDataObject(viz.use, dataName);
383 |             }
384 |             else dataObj = clone(viz.use);
385 |             if (track.inFacet && !track.facetData) track.facetData = dataObj;
386 |             else if (!track.inFacet || !equalDataObjects(track.facetData, dataObj)) {
387 |               final.data = dataObj;
388 |             }
389 |           }
390 |         };
391 | 
392 |         //spec types
393 |         if (type === 'unit') {
394 |           processData();
395 |         }
396 |         else if (type === 'facet') {
397 |           if (track.inFacet) {
398 |             throw Error('Vizsla does not currently support nested facets');
399 |           }
400 |           track.inFacet = true;
401 |           processData();
402 |           const child = viz.spec.spec;
403 |           if (child) final.spec = finalize(child, track);
404 |           if (track.facetData) final.data = track.facetData;
405 |           track.inFacet = false;
406 |           track.facetData = null;
407 |         }
408 |         else if (type === 'repeat') {
409 |           const child = viz.spec.spec;
410 |           if (child) {
411 |             final.spec = finalize(child, track);
412 |             const prop = (child.type === 'facet' ? 'facet' : 'encoding');
413 |             for (let direc in final.repeat) {
414 |               const chn = viz.repeatChannel[direc];
415 |               if (child.type === 'facet' && chn !== 'row' && chn !== 'column') {
416 |                 throw Error('only row and column channels can be used in a facet spec');
417 |               }
418 |               const channelObj = final.spec[prop][chn];
419 |               if (channelObj) channelObj.field = { repeat: direc };
420 |               else {
421 |                 final.spec[prop][chn] = { 
422 |                   field: { repeat: direc },
423 |                   type: 'quantitative'  
424 |                 };
425 |               }
426 |             }
427 |           }
428 |         }
429 |         else {  //layer, vconcat, hconcat
430 |           if (viz.spec[type]) {
431 |             final[type] = viz.spec[type].map(child => finalize(child, track));
432 |           }
433 |         }
434 | 
435 |         return final;
436 |       };
437 |       
438 |       //get final spec and use datasets property if required
439 |       const finalRoot = finalize(this, {}, true);
440 |       if (datasetsMap.size) {
441 |         const datasetsObj = {};
442 |         for (let [values, name] of datasetsMap.entries()) {
443 |           datasetsObj[name] = values;
444 |         }
445 |         finalRoot.datasets = datasetsObj;
446 |       }
447 |       return finalRoot;
448 | 
449 |     };
450 | 
451 |   }
452 |   
453 |   //export
454 |   module.exports = vz;
455 | 
456 | })();


--------------------------------------------------------------------------------