jupyter-ijavascript-utils 1.22.4 → 1.24.0

package/DOCS.md

@@ -63,8 +63,20 @@ This is not intended to be the only way to accomplish many of these tasks, and a
 
 ![Screenshot of example notebook](img/mainExampleNotebook.png)
 
+## Running on Binder
+
+[mybinder.org](https://mybinder.org/) is a great place to run a Jupyter Notebook online.
+
+It means you can run Jupyter Notebooks with additional kernels without having to install anything,
+and can try right in your browser.
+
+Give it a try here:
+[![Binder:what can I do with this](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/paulroth3d/jupyter-ijavascript-utils/main?labpath=example.ipynb)
+
 ## What's New
 
+* 1.24 - format.stripHtmlTags, TableGenerator.offset, chain.chainFlatMap, chain.chainFilter
+* 1.23 - add format.parseNumber and TableGenerator.styleColumn, align group.separateByFields to vega-lite fold transform
 * 1.22 - make chain iJavaScript aware, but still able to work outside of Jupyter
 * 1.21 - include {@link module:chain|chain} - simple monoid
 * 1.20 - fix vega dependency

package/Dockerfile

@@ -1,3 +1,3 @@
 # syntax=docker/dockerfile:1
 
-FROM darkbluestudios/jupyter-ijavascript-utils:binder_1.22.4
+FROM darkbluestudios/jupyter-ijavascript-utils:binder_1.24.0

package/README.md

@@ -55,6 +55,8 @@ This is not intended to be the only way to accomplish many of these tasks, and a
 
 # What's New
 
+* 1.24 - format.stripHtmlTags, TableGenerator.offset, chain.chainFlatMap, chain.chainFilter
+* 1.23 - add format.parseNumber and TableGenerator.styleColumn, align group.separateByFields to vega-lite fold transform
 * 1.22 - make chain iJavaScript aware, but still able to work outside of Jupyter
 * 1.21 - include chain - simple monoid
 * 1.20 - fix vega dependency
@@ -104,14 +106,13 @@ Steps Overview:
 
 ## Running on Binder
 
-!TODO
-
 [mybinder.org](https://mybinder.org/) is a great place to run a Jupyter Notebook online.
 
-We are still attempting to sort out a suitable link that will work for everyone
-(without overloading their service)
+It means you can run Jupyter Notebooks with additional kernels without having to install anything,
+and can try right in your browser.
 
-(Please see [Issue #4](https://github.com/paulroth3d/jupyter-ijavascript-utils/issues/4))
+Give it a try here:
+[![Binder:what can I do with this](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/paulroth3d/jupyter-ijavascript-utils/main?labpath=example.ipynb)
 
 # For Example
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jupyter-ijavascript-utils",
-  "version": "1.22.4",
+  "version": "1.24.0",
   "description": "Utilities for working with iJavaScript - a Jupyter Kernel",
   "homepage": "https://jupyter-ijavascript-utils.onrender.com/",
   "license": "MIT",

package/src/TableGenerator.js

@@ -105,6 +105,7 @@ const { createSort } = require('./array');
  * * sort and limit the output
  *   * {@link TableGenerator#filter|filter(fn)} - determine which rows to include or not
  *   * {@link TableGenerator#limit|limit(number)} - limit only specific # of rows
+ *   * {@link TableGenerator#offset|offset(number)} - starts results only after an offset number of rows
  *   * {@link TableGenerator#sortFn|sortFn(fn)} - Standard Array sort function
  *   * {@link TableGenerator#sort|sort(field, field, ...)} - sorts by fields, or descending with '-'
  * * transpose the output
@@ -112,6 +113,7 @@ const { createSort } = require('./array');
  * * style the table
  *   * {@link TableGenerator#styleTable|styleTable(string)} - css style for the table
  *   * {@link TableGenerator#styleHeader|styleHeader(string)} - css styles for the header row
+ *   * {@link TableGenerator#styleColumn|styleColumn(object)} - Function to style cells based on the column
  *   * {@link TableGenerator#styleRow|styleRow(fn)} - Function to style rows
  *   * {@link TableGenerator#styleCell|styleCell(fn)} - Function to style cells
  *   * {@link TableGenerator#border|border(string)} - Apply a border to the table data cells
@@ -196,6 +198,17 @@ class TableGenerator {
    */
   #limit = 0;
 
+  /**
+   * The number of rows to skip before showing results.
+   * 
+   * 10 : means start showing results only after the first 10 records
+   * 
+   * -10 : means only show the last 10
+   * 
+   * @type {Number}
+   */
+  #offset = 0;
+
   /**
    * PrintValue options to use when rendering the table values
    * @type {PrintOptions}
@@ -229,6 +242,12 @@ class TableGenerator {
    */
   #styleRow = null;
 
+  /**
+   * Style to apply at the column level
+   * @type {Function}
+   */
+  #styleColumn = null;
+
   /**
    * Style to apply at the cell
    * @type {Function}
@@ -282,11 +301,13 @@ class TableGenerator {
     this.#formatterFn = null;
     this.#labels = {};
     this.#limit = 0;
+    this.#offset = 0;
     this.#printOptions = null;
     this.#sortFn = null;
     this.#styleTable = '';
     this.#styleHeader = '';
     this.#styleRow = null;
+    this.#styleColumn = null;
     this.#styleCell = null;
     this.#isTransposed = false;
   }
@@ -386,6 +407,7 @@ class TableGenerator {
    * As this adds additional CSS, the styling applied:
    *   * {@link TableGenerator#styleTable|to the whole table}
    *   * or {@link TableGenerator#styleRow|to the rows}
+   *   * or {@link TableGenerator#styleColumn|to the column}
    *   * or {@link TableGenerator#styleCell|to the data cells} will be affected
    * 
    * For example:
@@ -668,6 +690,21 @@ class TableGenerator {
     return this;
   }
 
+  /**
+   * The number of rows to skip before showing any records.
+   * 
+   * 10 : means start showing results only after the first 10 records
+   * 
+   * -10 : means only show the last 10
+   * 
+   * @param {Number} offsetRecords - the number of rows to skip 
+   * @returns {TableGenerator} - chainable interface
+   */
+  offset(offsetRecords) {
+    this.#offset = offsetRecords;
+    return this;
+  }
+
   /**
    * Sets the alternative labels to be used for specific fields.
    * 
@@ -882,11 +919,99 @@ class TableGenerator {
     return this;
   }
 
+  /**
+   * Function that can apply a style to a given column
+   * 
+   * (rowIndex, ({ columnHeader, columnIndex, record, row, rowIndex, value })) => string
+   * 
+   * note: see {@link TableGenerator#styleCell} for another way to do style a cell.
+   * 
+   * ```
+   * dataSet = [
+   *   {reg: 'z', source: 'A', temp: 10},
+   *   {reg: 'z', source: 'B', temp: 98},
+   *   {reg: 'z', source: 'A', temp: 100}
+   * ];
+   * 
+   * utils.table(dataSet)
+   *   .styleColumn({
+   *     //-- we want to make the background color of the color red, if the temp > 50
+   *     temp: (temp) => temp > 50 ? 'background-color:pink' : '',
+   * 
+   *     //-- we want to make the source bold if the source is B
+   *     source: (source) => source === 'B' ? 'font-weight:bold' : ''
+   *   })
+   *   .render();
+   * ```
+   * <table cellspacing="0px" >
+   * <tr ><th>reg</th><th>source</th><th>temp</th></tr>
+   * <tr ><td >z</td><td >A</td><td >10</td></tr>
+   * <tr ><td >z</td><td style="font-weight:bold;">B</td><td style="background-color:pink;">98</td></tr>
+   * <tr ><td >z</td><td >A</td><td style="background-color:pink;">100</td></tr>
+   * </table>
+   * 
+   * Or you could style the cell based on information in other columns.
+   * 
+   * ```
+   * dataSet = [
+   *   {reg: 'z', source: 'A', tempFormat: 'c', temp: 42},
+   *   {reg: 'z', source: 'B', tempFormat: 'f', temp: 98},
+   *   {reg: 'z', source: 'A', tempFormat: 'f', temp: 100}
+   * ];
+   * 
+   * utils.table(dataSet)
+   *   .styleColumn({
+   *     //-- we want to make the background color of the color red, if the temp > 50
+   *     temp: (temp, { record }) => convertToKelvin(temp, record.tempFormat) > 283
+   *       ? 'background-color:pink'
+   *       : ''
+   *   })
+   *   .render();
+   * ```
+   * 
+   * <table cellspacing="0px" >
+   * <tr ><th>reg</th><th>source</th><th>tempFormat</th><th>temp</th></tr>
+   * <tr ><td >z</td><td >A</td><td >c</td><td style="background-color:pink;">10</td></tr>
+   * <tr ><td >z</td><td >B</td><td >f</td><td style="background-color:pink;">98</td></tr>
+   * <tr ><td >z</td><td >A</td><td >f</td><td style="background-color:pink;">100</td></tr>
+   * </table>
+   * 
+   * @param {object} styleObj - object with properties matching the column header label
+   * @param {function(value, contextObj)} styleObj.property - Function to evaluate for each row returning the inline css styles to apply.
+   * 
+   * When it runs it will get passed the value and context,
+   * and should return the css inline styles to apply
+   * 
+   * @param {any} styleObj.property.value - the value for a given row for that column
+   * @param {any}    styleObj.property.context.value - destructured value of the cell
+   * @param {Number} styleObj.property.context.columnIndex - destructured 0 index column of the cell
+   * @param {Number} styleObj.property.context.rowIndex - destructured 0 index row of the cell
+   * @param {Array}  styleObj.property.context.row - destructured full row provided
+   * @param {Array}  styleObj.property.context.record - destructured original record
+   * @returns {TableGenerator} - chainable instance
+   */
+  styleColumn(styleObj) {
+    if (!styleObj) {
+      this.#styleColumn = null;
+      return this;
+    }
+
+    if (typeof styleObj !== 'object') {
+      throw Error('styleColumn(styleObj): expects an object with properties matching the column LABELs');
+    }
+
+    this.#styleColumn = styleObj;
+
+    return this;
+  }
+
   /**
    * Function that can apply a style to a given cell
    * 
    * (value, columnIndex, rowIndex, row, record) => string
    * 
+   * Note: see {@link TableGenerator#styleColumn} for another way to do style a cell.
+   * 
    * ```
    * dataSet = [
    *  { title:'row 0', a: 0.608, b: 0.351, c: 0.823, d: 0.206, e: 0.539 },
@@ -914,13 +1039,14 @@ class TableGenerator {
    * ```
    * ![Screenshot of styling the cell](img/Table_StyleCell.png)
    * 
-   * @param {function(*):any} formatterFn - Translation function to apply to all cells.
    * 
    * When it runs, you will receive a single parameter representing the current cell and row.
    * 
    * Return what the new value should be.
+   * @param {function(*):any} formatterFn - Translation function to apply to all cells.
    * @param {any}    formatterFn.value - destructured value of the cell
    * @param {Number} formatterFn.columnIndex - destructured 0 index column of the cell
+   * @param {Number} formatterFn.columnHeader - destructured header of the column
    * @param {Number} formatterFn.rowIndex - destructured 0 index row of the cell
    * @param {Array}  formatterFn.row - destructured full row provided
    * @param {Array}  formatterFn.record - destructured original record
@@ -1032,8 +1158,12 @@ class TableGenerator {
 
     if (this.#limit < 0) {
       data = data.reverse().slice(0, -this.#limit);
+    } else if (this.#offset < 0) {
+      data = data.slice(this.#offset);
     } else if (this.#limit > 0) {
-      data = data.slice(0, this.#limit);
+      data = data.slice(this.#offset, this.#offset + this.#limit);
+    } else if (this.#offset > 0) {
+      data = data.slice(this.#offset);
     }
 
     if (this.#isTransposed) {
@@ -1061,6 +1191,7 @@ class TableGenerator {
     const styleTable = this.#styleTable;
     const styleHeader = this.#styleHeader;
     const styleRowFn = this.#styleRow;
+    const styleColumnObj = this.#styleColumn;
     const styleCellFn = this.#styleCell;
     const printOptions = this.#printOptions;
     const borderCSS = this.#borderCSS;
@@ -1099,14 +1230,20 @@ class TableGenerator {
 
         return `<tr ${printInlineCSS(rowStyle)}>\n\t`
           + dataRow.map((value, columnIndex) => {
+            const columnHeader = results.headers[columnIndex];
             //-- style for the cell
-            const cellStyle = !styleCellFn ? '' : styleCellFn({ value, columnIndex, rowIndex, row: dataRow, record });
+            const cellData = { value, columnIndex, columnHeader, rowIndex, row: dataRow, record };
+            const cellStyle = !styleCellFn ? '' : styleCellFn(cellData);
+            const columnStyle = !styleColumnObj || !styleColumnObj[columnHeader] || !typeof styleColumnObj[columnHeader] === 'function'
+              ? ''
+              : styleColumnObj[columnHeader](value, cellData);
 
             return `<td ${
               printInlineCSS(
                 borderCSS,
                 //-- could be inline, but not as clear
-                cellStyle
+                cellStyle,
+                columnStyle
               )
             }>${
               cleanFn(value, printOptions)

package/src/chain.js

@@ -13,6 +13,9 @@
  * * {@link ChainContainer#close|.close()} - gets the value of the current chain
  * * {@link ChainContainer#chain|.chain(function)} - where it is passed the value, and returns a new Chain with that value.
  * * {@link ChainContainer#chainMap|.chainMap(function)} - where it treats value as an array, and maps function on every item in the array
+ * * {@link ChainContainer#chainFlatMap|.chainFlatMap(function)} - where it treats value as an array, and maps function on every item in the array,
+ *        flattening the results
+ * * {@link ChainContainer#chainFilter|.chainFilter(function)} - where it treats the value as an array, and filters values based on the result
  * * {@link ChainContainer#chainReduce|.chainReduce(function, initialValue)} - where it treats value as an array, and reduces the value array
  * * {@link ChainContainer#errorHandler|.errorHandler(fn)} - custom function called if an error is ever thrown
  * * {@link ChainContainer#debug|.debug()} - console.logs the current value, and continues the chain with that value
@@ -158,6 +161,69 @@ class ChainContainer {
     return this.chain((value) => value.map(fn));
   }
 
+  /**
+   * Assuming that value is an array, performs a
+   * [javaScript flatMap](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/flatMap)
+   * against the results.
+   * 
+   * This can be very helpful in expanding the list of items in an array, or removing items from an array.
+   * 
+   * ```
+   * // expanding size of the array
+   * initializeArray = (size) => Array.from(Array(size)).map((val, index) => index);
+   * initializeArray(3); // [0, 1, 2]
+   * 
+   * utils.chain([1, 2, 3, 4])
+   *  .chainFlatMap(initializeArray)
+   *  .close();
+   * 
+   * // [1, 1, 2, 1, 2, 3, 1, 2, 3, 4];
+   * ```
+   * 
+   * or similar to {@link ChainContainer#chainFilter|chainFilter}
+   * 
+   * ```
+   * // reducing the size of the array
+   * filterOdd = (value) => value % 2 === 0 ? [value] : [];
+   * filterOdd(2); // [2]
+   * filterOdd(1); // []
+   * 
+   * chain([1, 2, 3, 4, 5])
+   *  .chainFlatMap(filterOdd)
+   *  .close();
+   * 
+   * // [2, 4];
+   * ```
+   * 
+   * @param {function(any):any} fn - function that can either return a value or array of values.
+   * @returns {ChainContainer}
+   * @see {@link ChainContainer#chainFilter} - for other options in filtering
+   */
+  chainFlatMap(fn) {
+    if (!Array.isArray(this.value)) throw Error(`chainFlatMap expects an array, but was passed:${this.value}`);
+
+    return this.chain((value) => value.flatMap(fn));
+  }
+
+  /**
+   * Assuming that value is an array, this maps fn to filter the results in the array.
+   * 
+   * ```
+   * chain([1,2,3,4])
+   *    .chainFilter((value) => value < 3)
+   *    .close();
+   * // [1, 2]
+   * ```
+   * 
+   * @param {function(any):Boolean} fn - Function accepting a value and returning whether it should be included (true) or not (false)
+   * @returns {ChainContainer}
+   */
+  chainFilter(fn) {
+    if (!Array.isArray(this.value)) throw Error(`chainFilter expects an array, but was passed:${this.value}`);
+
+    return this.chain((value) => value.filter(fn));
+  }
+
   /**
    * Assuming that the value is an array, performs a reduce using fn and initialValue
    * 
@@ -361,6 +427,9 @@ class ChainContainer {
  * * {@link ChainContainer#close|.close()} - gets the value of the current chain
  * * {@link ChainContainer#chain|.chain(function)} - where it is passed the value, and returns a new Chain with that value.
  * * {@link ChainContainer#chainMap|.chainMap(function)} - where it treats value as an array, and maps function on every item in the array
+ * * {@link ChainContainer#chainFlatMap|.chainFlatMap(function)} - where it treats value as an array, and maps function on every item in the array,
+ *        flattening the results
+ * * {@link ChainContainer#chainFilter|.chainFilter(function)} - where it treats the value as an array, and filters values based on the result
  * * {@link ChainContainer#chainReduce|.chainReduce(function, initialValue)} - where it treats value as an array, and reduces the value array
  * * {@link ChainContainer#errorHandler|.errorHandler(fn)} - custom function called if an error is ever thrown
  * * {@link ChainContainer#debug|.debug()} - console.logs the current value, and continues the chain with that value

package/src/format.js

@@ -15,6 +15,7 @@
  *   * {@link module:format.capitalize|format.capitalize} - Capitalizes only the first character in the string (ex: 'John paul');
  *   * {@link module:format.capitalizeAll|format.capitalizeAll} - Capitalizes all the words in a string (ex: 'John Paul')
  *   * {@link module:format.ellipsify|format.ellipsify} - Truncates a string if the length is 'too long'
+ *   * {@link module:format.stripHtmlTags|format.stripHtmlTags} - removes html / xml tags from strings.
  *   * {@link module:format.limitLines|format.limitLines(string, toLine, fromLine, lineSeparator)} - selects only a subset of lines in a string
  *   * {@link module:format.consoleLines|format.consoleLines(...)} - same as limit lines, only console.logs the string out.
  * * Formatting Time
@@ -29,6 +30,9 @@
  *   * {@link module:format.safeConvertFloat|format.safeConvertFloat} - converts a value to a Number (123.4), or uses a default for any error or NaN
  *   * {@link module:format.safeConvertInteger|format.safeConvertInteger} - converts a value to a Number (123), or uses a default for any error or NaN
  *   * {@link module:format.safeConvertBoolean|format.safeConvertBoolean} - converts a value to a boolean
+ * * Parsing values
+ *   * {@link module:format.parseBoolean|format.parseBoolean(val)} - converts a value to a boolean value
+ *   * {@link module:format.parseNumber|format.parseNumber(val, locale)} - converts a value to a number
  * * Identifying values
  *   * {@link module:format.isEmptyValue|format.isEmptyValue} - determine if a value is not 'empty'
  * 
@@ -877,6 +881,51 @@ module.exports.isBoolean = function isBoolean(val) {
     || val === 'true' || val === 'false';
 };
 
+FormatUtils.parseLocaleCache = new Map();
+
+/**
+ * Parses a given number, based on a {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat|Intl.NumberFormat}
+ * 
+ * If the locale is not passed (ex: 'fr-FR'), then 'en-US' is assumed
+ * 
+ * @param {any} val - value to parse
+ * @returns {Number} - parsed number
+ * @example
+ * 
+ * utils.format.parseNumber(10); // 10
+ * utils.format.parseNumber('10'); // 10
+ * utils.format.parseNumber('1,000'); // 1000
+ * utils.format.parseNumber('1,000.5'); // 1000.5
+ * utils.format.parseNumber('1,000', 'en-US'); // 1000
+ * utils.format.parseNumber('1,000.5', 'en-US'); // 1000.5
+ * utils.format.parseNumber('1 000', 'fr-FR'); // 1000
+ * utils.format.parseNumber('1 000,5', 'fr-FR'); // 1000.5
+ */
+module.exports.parseNumber = function parseNumber(val, locale = 'en-US') {
+  const valType = typeof val;
+  if (valType === 'number') {
+    return val;
+  } else if (valType === 'string') {
+    let separator;
+    if (FormatUtils.parseLocaleCache.has(locale)) {
+      separator = FormatUtils.parseLocaleCache.get(locale);
+    } else {
+      const example = Intl.NumberFormat(locale).format('1.1');
+      separator = example.charAt(1);
+      FormatUtils.parseLocaleCache.set(locale, separator);
+    }
+
+    const cleanPattern = new RegExp(`[^-+0-9${separator}]`, 'g');
+    const cleaned = val.replace(cleanPattern, '');
+    const normalized = cleaned.replace(separator, '.');
+
+    return parseFloat(normalized);
+  } else if (!val) {
+    return val;
+  }
+  return parseFloat(val);
+};
+
 /**
  * Narrows to only fromLine - toLine (inclusive) within a string.
  * 
@@ -929,3 +978,21 @@ module.exports.limitLines = function limitLines(str, toLine, fromLine, lineSepar
 module.exports.consoleLines = function consoleLines(str, toLine, fromLine, lineSeparator) {
   console.log(FormatUtils.limitLines(str, toLine, fromLine, lineSeparator));
 };
+
+/**
+ * Strips any html or xml tags from a string.
+ * 
+ * Note, if you want to remove html entities (ex: ` ` or `‑`), please consider [other libraries](https://www.npmjs.com/search?q=html%20entities)
+ * 
+ * @param {String} str - string to strip html / xml entities from
+ * @returns {String}
+ * @example 
+ * 
+ * utils.format.stripHtmlTags('Hello <br />Nice to see <b>you</b>'); // 'Hello Nice to see you'
+ * utils.format.stripHtmlTags('example string'); // 'example string' -- untouched
+ */
+module.exports.stripHtmlTags = function stripHtmlTags(str) {
+  if (!str) return str;
+
+  return str.replace(/<[^>]+>/g, '');
+};

package/src/group.js

@@ -215,6 +215,8 @@ module.exports.rollup = function rollup(collection, reducer, prop, ...fields) {
  * 
  * The object generated by the function is then merged.
  * 
+ * See [vega-lite fold transform](https://vega.github.io/vega-lite/docs/fold.html)
+ * 
  * @example
  * aggregateWeather = utils.group.by(weather, 'city')
  *   .reduce((group) => ({
@@ -235,12 +237,12 @@ module.exports.rollup = function rollup(collection, reducer, prop, ...fields) {
  * 
  * //-- gives
  * [
- *   { city: 'Seattle', min: 0.87, max: 5.31, avg: 2.953,  _field: 'min', _value: 0.87 },
- *   { city: 'New York', min: 3.58, max: 4.13, avg: 3.883, _field: 'min', _value: 3.58 },
- *   { city: 'Chicago', min: 2.56, max: 3.98, avg: 3.387,  _field: 'min', _value: 2.56 },
- *   { city: 'Seattle', min: 0.87, max: 5.31, avg: 2.953,  _field: 'max', _value: 5.31 },
- *   { city: 'New York', min: 3.58, max: 4.13, avg: 3.883, _field: 'max', _value: 4.13 },
- *   { city: 'Chicago', min: 2.56, max: 3.98, avg: 3.387,  _field: 'max', _value: 3.98},
+ *   { city: 'Seattle', min: 0.87, max: 5.31, avg: 2.953,  key: 'min', value: 0.87 },
+ *   { city: 'New York', min: 3.58, max: 4.13, avg: 3.883, key: 'min', value: 3.58 },
+ *   { city: 'Chicago', min: 2.56, max: 3.98, avg: 3.387,  key: 'min', value: 2.56 },
+ *   { city: 'Seattle', min: 0.87, max: 5.31, avg: 2.953,  key: 'max', value: 5.31 },
+ *   { city: 'New York', min: 3.58, max: 4.13, avg: 3.883, key: 'max', value: 4.13 },
+ *   { city: 'Chicago', min: 2.56, max: 3.98, avg: 3.387,  key: 'max', value: 3.98},
  *   ...
  * ]
  * 
@@ -256,7 +258,7 @@ module.exports.separateByFields = function separateByFields(collection, ...field
   if (!fields || !Array.isArray(fields) || fields.length < 1) {
     throw (Error('separateByFields: fields are expected'));
   }
-  return fields.flatMap((field) => collection.map((obj) => ({ ...obj, _field: field, _value: obj[field] })));
+  return fields.flatMap((field) => collection.map((obj) => ({ ...obj, key: field, value: obj[field] })));
 };
 
 /**

package/src/vega.js

@@ -8,6 +8,9 @@ const IJSUtils = require('./ijs');
 /**
  * Helper for working with [Vega-Lite](https://vega.github.io/vega-lite/) (and [Vega](https://vega.github.io/vega/)) within iJavaScript notebooks.
  * 
+ * * [Vega-Lite Example Gallery](https://vega.github.io/vega-lite/examples/)
+ * * [Vega Example Gallery](https://vega.github.io/vega/examples/)
+ * 
  * ([Vega-Lite-Api](https://vega.github.io/vega-lite-api/):
  * creates -> [Vega-Lite JSON specifications](https://vega.github.io/vega-lite/tutorials/getting_started.html):
  * creates -> [Vega charting specifications](https://vega.github.io/):
@@ -25,6 +28,39 @@ const IJSUtils = require('./ijs');
  * * Rendering specifications through the Jupyter Lab mime-type
  *   * {@link module:vega.vegaMimeType|vega.vegaMimeType(Object | String)} - render the chart using the Vega mime-type (as png)
  *   * {@link module:vega.vegaLiteMimeType|vega.vegaLiteMimeType(Object | String)} - render the chart using the Vega-Lite mime-type (as png)
+ * 
+ * For example, this is a very simple demonstration for writing a vega-lite chart (the simplest way to get started)
+ * 
+ * ```
+ *  simpleData = [{fruit:'Apples',yield:20,year:'2020'},{fruit:'Apples',yield:22,year:'2021'},
+ *    {fruit:'Bananas',yield:15,year:'2020'},{fruit:'Bananas',yield:12,year:'2021'},
+ *    {fruit:'Pears',yield:18,year:'2020'},{fruit:'Pears',yield:19,year:'2021'}];
+ *  
+ *  utils.vega.svg(
+ *  // accept the reference to the vega-lite instance passed
+ *  (vl) => vl
+ *    // render as points
+ *    .markPoint()
+ *        // use simpleData as the data source
+ *        .data(simpleData)
+ *        // title
+ *        .title('Fruit by Yield')
+ *        .width(100)
+ *        .encode(
+ *            // define the x axis as the Qualitative / Numerical 'yield' property
+ *            vl.y().fieldQ('yield'),
+ *            // define the y axis as the Nominative / TextBased 'fruit' property
+ *            vl.x().fieldN('fruit'),
+ *            // define the color series based on the Qualitative / Numerical 'year' property
+ *            vl.color().fieldN('year')
+ *        )
+ *  );
+ *  ```
+ * ![Screenshot](img/vegaSimpleChart.jpg)
+ * 
+ * and with simple changes, convert it to a bar graph
+ * 
+ * ![Screenshot](img/fruitYieldByYearBar.png)
  * -----
  * 
  * * Check out the {@tutorial vegaLite1} tutorials
@@ -155,6 +191,7 @@ const IJSUtils = require('./ijs');
  *     "x": {"field": "Horsepower", "type": "quantitative"},
  *     "y": {"field": "Miles_per_Gallon", "type": "quantitative"},
  *     "color": {"field": "Origin", "type": "nominal"},
+ *     //-- simply by adding the tooltip encoding here
  *     "tooltip": {"field": "Name", "type": "nominal"},
  *     "href": {"field": "url", "type": "nominal"}
  *   }
@@ -163,6 +200,132 @@ const IJSUtils = require('./ijs');
  * 
  * ![Screenshot for tooltips](img/vegaScript_tooltips.png)
  * 
+ * or through the vega lite
+ * 
+ * ---
+ * 
+ * # FAQ
+ * 
+ * The following are a series of common questions / issues, put here for visibility.
+ * 
+ * ## Passing Objects to vega-lite-api
+ * 
+ * Note that there are some things that are not supported by the vega-lite-api <br />
+ * ([such as grouping](https://github.com/vega/vega-lite/issues/4703))
+ * 
+ * This is only a problem with the vega-lite-api, as it writes the spec used for vega-lite
+ * 
+ * In these cases, you can send an object within many of the methods,
+ * as it no longer needs to translate how that object should look.
+ * 
+ * (like sending `mark( type:'bar')` instead of `.markBar()` - to allow for tooltips <br />
+ * or passing an object to encode to support grouping)
+ * 
+ * ```
+ * simpleData = [{fruit:'Apples',yield:20,year:'2020'},{fruit:'Apples',yield:22,year:'2021'},
+ *   {fruit:'Bananas',yield:15,year:'2020'},{fruit:'Bananas',yield:12,year:'2021'},
+ *   {fruit:'Pears',yield:18,year:'2020'},{fruit:'Pears',yield:19,year:'2021'}];
+ *  
+ * utils.vega.svg((vl) => vl
+ *   // render as points
+ *   .mark({ type: 'bar', tooltip: true})
+ *   .data(simpleData)
+ *   .title('Fruit by Yield')
+ *   .width(100)
+ *   .encode({
+ *     "x": {"field": "fruit"},
+ *     "y": {"field": "yield", "type": "quantitative"},
+ *     "xOffset": {"field": "year"},
+ *     "color": {"field": "year"}
+ *   })
+ * );
+ * ```
+ * 
+ * ![Screenshot](img/vega_groupedBarCharts.jpg)
+ * 
+ * ---
+ * 
+ * ## Chart Series
+ * 
+ * Instead of grouping values, you can also create a series of charts instead.
+ * 
+ * ```
+ * utils.vega.svg((vl) => vl
+ *   // render as points
+ *   .mark({ type: 'arc', innerRadius: 30, tooltip: true})
+ *       .data(simpleData)
+ *       .title('Fruit by Yield')
+ *       .width(100)
+ *       .encode(
+ *         // define the arc on the graph with the Qualitative / Numerical 'yield' property
+ *         vl.theta().fieldQ('yield'),
+ *         // define the y axis as the based on the Qualitative / Numerical 'year' property
+ *         vl.color().fieldN('year'),
+ *         // define the color series Nominative / TextBased 'fruit' property
+ *         vl.column().fieldN('fruit')
+ *       )
+ * );
+ * ```
+ * 
+ * ![Screenshot](img/vega_chartColumns.jpg)
+ * 
+ * Other examples can be found [under the vega-lite examples](https://vega.github.io/vega-lite/examples/#repeat--concatenation)
+ * and rendered with {@link vega.svgFromSpec|svgFromSpec} or {@link vega.ßembedFromSpec|embedFromSpec}
+ * 
+ * ---
+ * 
+ * ## Object Formatting / Conversion
+ * 
+ * Note that vega-lite examples use data at the mark level:
+ * 
+ * ```
+ * [{fruit:'Apples',yield:20,year:'2020'},{fruit:'Apples',yield:22,year:'2021'},
+ *   {fruit:'Bananas',yield:15,year:'2020'},{fruit:'Bananas',yield:12,year:'2021'},
+ *   {fruit:'Pears',yield:18,year:'2020'},{fruit:'Pears',yield:19,year:'2021'}];
+ * ```
+ * 
+ * not at the series level:
+ * 
+ * ```
+ * [{ year:'2020', apples:20, bananas:15, pears:18 },
+ *  { year:'2021', apples:22, bananas:12, pears:19 }];
+ * ```
+ * 
+ * If your data is at the series level, you can:
+ * 
+ * * Transform the data with the {@link module:group.separateByFields|group.separateByFields}
+ *     * utils.group.separateByFields(fruitSeriesData, 'apples', 'bananas', 'pears');
+ *     * this makes a new field called 'key' that will have values of either apples, bananas or pears
+ * * or using the [vega-lite fold transform](https://vega.github.io/vega-lite/docs/fold.html)
+ *     * by adding in the `.transform()` into the spec - like below
+ * 
+ * ```
+ * fruitSeriesData = [{ year:'2020', apples:20, bananas:15, pears:18 },
+ *   { year:'2021', apples:22, bananas:12, pears:19 }];
+ * 
+ * utils.vega.svg((vl) => vl
+ *   .mark({ type: 'arc', innerRadius: 30, tooltip: true})
+ *     .data(fruitSeriesData)
+ * 
+ *     //-- apples, bananas and pears will now be separate records
+ *     //-- with the new `key` field as either 'apple', 'banana', or 'pears'
+ *     //-- and the new `value` field storing the value of those fields.
+ *     .transform([{ fold: ['apples', 'bananas', 'pears']}])
+ * 
+ *     .title('Fruit by Yield')
+ *     .width(100)
+ *     .encode(
+ *       // define the arc on the graph with the Qualitative / Numerical 'yield' property
+ *       vl.theta().fieldQ('value'),
+ *       // define the y axis as the Nominative / TextBased 'fruit' property
+ *       vl.color().fieldN('year'),
+ *       // define the color series based on the Qualitative / Numerical 'year' property
+ *       vl.column().fieldN('key')
+ *     )
+ * )
+ * ```
+ * ![Screenshot](img/vega_chartColumns.jpg)
+ * 
  * ---
  * 
  * For more: