jupyter-ijavascript-utils 1.52.0 → 1.53.0

package/DOCS.md

@@ -74,6 +74,7 @@ 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.53 - additional docs and examples for {@link module:color|color/colour} package.
 * 1.52 - print a date to ISO in local time with {@link module:date.toLocalISO|date.toLocalISO}
 * 1.51 - added in {@link module:date|date} - and addressed issue #69, #68, #67, #66
 * 1.50 - added in {@link module:color|color/colour} - and addressed issue #65

package/Dockerfile

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

package/README.md

@@ -54,6 +54,7 @@ This is not intended to be the only way to accomplish many of these tasks, and a
 ![Screenshot of example notebook](docResources/img/mainExampleNotebook.png)
 
 # What's New 
+* 1.53 - additional docs and examples for color/colour package.
 * 1.52 - print a date to ISO in local time with date.toLocalISO
 * 1.51 - added in date - and addressed issues #69, #68, #67, #66
 * 1.50 - added in color/colour - and addressed issue #65

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "jupyter-ijavascript-utils",
-  "version": "1.52.0",
+  "version": "1.53.0",
   "description": "Utilities for working with iJavaScript - a Jupyter Kernel",
   "homepage": "https://jupyter-ijavascript-utils.onrender.com/",
   "license": "MIT",
@@ -46,7 +46,7 @@
     "sinon": "^11.1.1"
   },
   "dependencies": {
-    "@svgdotjs/svg.js": "^3.1.2",
+    "@svgdotjs/svg.js": "^3.2.4",
     "fs-extra": "^10.0.1",
     "generate-schema": "^2.6.0",
     "node-fetch": "^2.6.5",

package/src/color.js

@@ -49,6 +49,33 @@
  *      a function of signature (fromColor:Number[0-255], toColor:Number[0-255], percentage:Number[0-1]):Number[0-255]
  *   * {@link module:color.INTERPOLATION_STRATEGIES|color.INTERPOLATION_STRATEGIES} - a list of strategies for interpolation you can choose from
  * 
+ * ```
+ * utils.svg.render({ width: 800, height: 100,
+ *     onReady: ({el, width, height, SVG }) => {
+ *         const fromColor = '#ff0000';
+ *         const toColor = 'rgb(0, 255, 0)';
+ * 
+ *         const numBoxes = 5;
+ *         const boxWidth = width / numBoxes;
+ *         const boxHeight = 100;
+ * 
+ *         // utils.color.interpolationStrategy = utils.color.INTERPOLATION_STRATEGIES.linear;
+ *         // utils.color.defaultFormat = utils.color.FORMATS.hex;
+ * 
+ *         const colorSequence = utils.color.generateSequence(fromColor, toColor, numBoxes);
+ *         // [ '#ff0000', '#9d6200', '#4bb400', '#13ec00', '#00ff00' ]
+ * 
+ *         colorSequence.forEach((boxColor, boxIndex) => {
+ *             el.rect(boxWidth, boxHeight)
+ *                 .fill(boxColor)
+ *                 .translate(boxIndex * boxWidth);
+ *         });
+ *     }
+ * });
+ * ```
+ * 
+ * ![Example SVG](img/interpolationExample.svg)
+ * 
  * @module color
  * @exports color
  */
@@ -68,13 +95,28 @@ module.exports.COLOR_VALIDATION = {
  * Enum strings of types expected
  * 
  * There are 6 types of formats supported:
- * * Hex - 6-8 character hexadecimal colors as RRGGBB or RRGGBBAA, like red for #ff0000 or #ff000080 for semi-transparency
- * * Hex3 - 3-4 character hexadecimal colors: RGB or RGBA, like red for #F00 or #F008 for semi-transparency
+ * * HEX - 6 character hexadecimal colors as RRGGBB, like red for #ff0000
+ *   * alternatively - 3 character hexadecimal colors #RGB are supported: like red for #F00
+ * * HEXA - 8 character hexadecimal colors as RRGGBBAA, like red for #ff000080 with semi-transparency
+ *   * alternatively - 4 character hexadecimal colors #RGBA are supported: #F008
  * * RGB - color with format `rgb(RR,GG,BB)` - like red for `rgb(255,0,0)`
  * * RGBA - RGB format with alpha: `rgba(RR,GG,BB,AA)` - like red for `rgba(255,0,0,0.5)` for semi-transparency
  * * ARRAY - 3 to 4 length array, with format: `[r,g,b]` or `[r,g,b,a]` - like red for [255,0,0] or [255,0,0,0.5] for semi-transparency
  * * OBJECT - objects with properties: r, g, b and optionally: a (the object is not modified and only those properties are checked)
  * 
+ * For example:
+ * 
+ * ```
+ * baseColor = '#b1d1f3';
+ * 
+ * utils.color.convert(baseColor, utils.color.FORMATS.HEX); // '#b1d1f3'
+ * utils.color.convert(baseColor, utils.color.FORMATS.HEXA); // #b1d1f3ff
+ * utils.color.convert(baseColor, utils.color.FORMATS.RGB); // rgb( 177, 209, 243)
+ * utils.color.convert(baseColor, utils.color.FORMATS.RGBA); // rgba(177, 209, 243, 1)
+ * utils.color.convert(baseColor, utils.color.FORMATS.ARRAY); // [ 177, 209, 243, 1 ]
+ * utils.color.convert(baseColor, utils.color.FORMATS.OBJECT); // { r: 177, g: 209, b: 243, a: 1 }
+ * ```
+ * 
  * @see {@link module:color.defaultFormat|color.defaultFormat}
  */
 module.exports.FORMATS = {
@@ -90,6 +132,13 @@ module.exports.FORMATS = {
  * Default format used when converting to types
  * (allowing the conversion type to be optional)
  * 
+ * ```
+ * baseColor = '#b1d1f3';
+ * utils.color.defaultFormat = utils.color.FORMATS.RGBA;
+ * 
+ * utils.color.convert(baseColor); // rgba(177, 209, 243, 1)
+ * ```
+ * 
  * @see {@link module:color.FORMATS|color.FORMATS}
  */
 module.exports.defaultFormat = ColorUtils.FORMATS.HEX;
@@ -99,6 +148,8 @@ const PI2 = Math.PI * 0.5;
 /**
  * Different types of interpolation strategies:
  * 
+ * ![example](img/interpolationStrategies.svg)
+ * 
  * * linear - linear interpolation between one value to another (straight line)
  * * easeInOut - slows in to the change and slows out near the end
  * * easeIn - slow then fast
@@ -114,10 +165,34 @@ module.exports.INTERPOLATION_STRATEGIES = {
 };
 
 /**
- * Which interpolation strategy to use when interpolating between colors
+ * Default interpolation strategy used when interpolating
+ * from one color to another.
  * 
  * (Defaults to linear)
  * 
+ * ![example](img/interpolationStrategies.svg)
+ * 
+ * For example, you can specify how you would like to interpolate
+ * and even which format you'd like to receive the results in.
+ * 
+ * ```
+ * //-- same as utils.color.INTERPOLATION_STRATEGIES.linear;
+ * linear = (a, b, pct) => a + (b - a) * pct;
+ * format = utils.color.FORMATS.ARRAY;
+ * utils.color.interpolate(red, green, 0, linear, format); // [255, 0, 0, 1]
+ * ```
+ * 
+ * or instead, you can set this property and set the default
+ * 
+ * ```
+ * // or set the default
+ * utils.color.interpolationStrategy = linear;
+ * utils.color.defaultFormat = utils.color.FORMATS.ARRAY;
+ * 
+ * //-- note that the interpolation strategy or format isn't passed
+ * utils.color.interpolate(red, green, 0.5); // [127.5, 127.5, 0, 1]
+ * ```
+ * 
  * @see {@link module:color.INTERPOLATION_STRATEGIES}
  */
 module.exports.interpolationStrategy = ColorUtils.INTERPOLATION_STRATEGIES.linear;
@@ -211,7 +286,8 @@ module.exports.parseHex = function parseHex(hexStr, optionalAlpha = 1) {
  */
 module.exports.toHex = function toHex(target) {
   const [r, g, b] = ColorUtils.parse(target);
-  return `#${r.toString(16)}${g.toString(16)}${b.toString(16)}`;
+  const hexOut = (num) => num.toString(16).padStart(2, '0');
+  return `#${hexOut(r)}${hexOut(g)}${hexOut(b)}`;
 };
 
 /**
@@ -511,6 +587,7 @@ module.exports.parse = function parse(target, optionalAlpha = 1) {
  * ```
  * 
  * @param {string|array|object} target - any of the Formats provided
+ * @param {string} [formatType = color.defaultFormat] - optional format to convert to, if not using the default
  * @returns {string|array|object} - any of the format types provided
  * 
  * @see {@link module:color.defaultFormat|color.defaultFormat} - to set the default format
@@ -621,7 +698,6 @@ module.exports.interpolate = function interpolate(
  * 
  * @param {string|array|object} fromColor -the color to interpolate from
  * @param {string|array|object} toColor - the color to interpolate to
- * @param {Number} percent - value from 0-1 on where we should be on the sliding scale
  * @param {Function} [interpolationFn = ColorUtils.interpolationStrategy] - function of
  *  signature (fromVal:Number[0-255], toVal:Number[0-255], pct:Number[0-1]):Number[0-255]
  * @param {String} [formatType = ColorUtils.defaultFormat] - the format to convert the result to 

package/src/date.js

@@ -311,9 +311,10 @@ module.exports.epochShift = function epochShift(date, timeZoneStr) {
  * Consider this as an alternative to epochShifting.
  * 
  * ```
- * d = new Date(Date.toISO(2024, 12, 26, 12, 30, 0));
+ * d = Date.parse('2024-12-27 13:30:00');
  * 
- * utils.date.toLocalISO(d, 'america/Chicago'); // '2024-12-16T06:30:00.000+05:30Z'
+ * utils.date.toLocalISO(d, 'america/Chicago'); // '2024-12-27T07:30:00.000-06:00'
+ * utils.date.toLocalISO(d, 'europe/paris'); //    '2024-12-27T14:30:00.000+01:00'
  * ```
  * 
  * @param {Date} date - date to print
@@ -461,10 +462,10 @@ class DateRange {
    * @param {DateRange} targetDateRange - dateRange to compare
    * @returns {Boolean}
    * @example
-   * overlapA = new Date(Date.UTC(2024, 12, 26, 12, 0, 0));
-   * overlapB = new Date(Date.UTC(2024, 12, 26, 13, 0, 0));
-   * overlapC = new Date(Date.UTC(2024, 12, 26, 14, 0, 0));
-   * overlapD = new Date(Date.UTC(2024, 12, 26, 15, 0, 0));
+   * overlapA = new Date(Date.UTC(2024, 11, 26, 12, 0, 0));
+   * overlapB = new Date(Date.UTC(2024, 11, 26, 13, 0, 0));
+   * overlapC = new Date(Date.UTC(2024, 11, 26, 14, 0, 0));
+   * overlapD = new Date(Date.UTC(2024, 11, 26, 15, 0, 0));
    * 
    * rangeBefore = new utils.DateRange(overlapA, overlapB);
    * rangeAfter = new utils.DateRange(overlapC, overlapD);
@@ -490,10 +491,10 @@ class DateRange {
    * @returns {Boolean} - if the value is within the range (true) or not (false)
    * 
    * @example
-   * withinA = new Date(Date.UTC(2024, 12, 26, 12, 0, 0));
-   * withinB = new Date(Date.UTC(2024, 12, 26, 13, 0, 0));
-   * withinC = new Date(Date.UTC(2024, 12, 26, 14, 0, 0));
-   * withinD = new Date(Date.UTC(2024, 12, 26, 15, 0, 0));
+   * withinA = new Date(Date.UTC(2024, 11, 26, 12, 0, 0));
+   * withinB = new Date(Date.UTC(2024, 11, 26, 13, 0, 0));
+   * withinC = new Date(Date.UTC(2024, 11, 26, 14, 0, 0));
+   * withinD = new Date(Date.UTC(2024, 11, 26, 15, 0, 0));
    * 
    * range = new utils.DateRange(withinB, withinD);
    * range.contains(withinA); // false - it was before the range
@@ -512,8 +513,8 @@ class DateRange {
    * Determines the millisecond duration between the end and start time.
    * 
    * ```
-   * durationA = new Date(Date.UTC(2024, 12, 26, 12, 0, 0));
-   * durationB = new Date(Date.UTC(2024, 12, 26, 13, 0, 0));
+   * durationA = new Date(Date.UTC(2024, 11, 26, 12, 0, 0));
+   * durationB = new Date(Date.UTC(2024, 11, 26, 13, 0, 0));
    * range = new utils.DateRange(durationA, durationB);
    * 
    * range.durationString(); // 1 hour in milliseconds; 1000 * 60 * 60;
@@ -529,8 +530,8 @@ class DateRange {
    * Determines the duration in a clear and understandable string;
    * 
    * ```
-   * durationA = new Date(Date.UTC(2024, 12, 26, 12, 0, 0));
-   * durationB = new Date(Date.UTC(2024, 12, 26, 13, 0, 0));
+   * durationA = new Date(Date.UTC(2024, 11, 26, 12, 0, 0));
+   * durationB = new Date(Date.UTC(2024, 11, 26, 13, 0, 0));
    * range = new utils.DateRange(durationA, durationB);
    * 
    * range.durationString(); // '0 days, 1 hours, 0 minutes, 0.0 seconds';
@@ -547,8 +548,8 @@ class DateRange {
    * Determines the duration in days:hours:minutes:seconds.milliseconds
    * 
    * ```
-   * durationA = new Date(Date.UTC(2024, 12, 26, 12, 0, 0));
-   * durationB = new Date(Date.UTC(2024, 12, 26, 13, 0, 0));
+   * durationA = new Date(Date.UTC(2024, 11, 26, 12, 0, 0));
+   * durationB = new Date(Date.UTC(2024, 11, 26, 13, 0, 0));
    * range = new utils.DateRange(durationA, durationB);
    * 
    * range.durationString(); // '0:01:00:00.0000';
@@ -574,8 +575,8 @@ class DateRange {
    * Converts the daterange to a string value
    * 
    * ```
-   * durationA = new Date(Date.UTC(2024, 12, 26, 12, 0, 0));
-   * durationB = new Date(Date.UTC(2024, 12, 26, 13, 0, 0));
+   * durationA = new Date(Date.UTC(2024, 11, 26, 12, 0, 0));
+   * durationB = new Date(Date.UTC(2024, 11, 26, 13, 0, 0));
    * range = new utils.DateRange(durationA, durationB);
    * 
    * range.toString(); // '2025-01-26T12:00:00.000Z to 2025-01-26T13:00:00.000Z';
@@ -591,8 +592,8 @@ class DateRange {
    * Converts the daterange to a local string value
    * 
    * ```
-   * durationA = new Date(Date.UTC(2024, 12, 26, 12, 0, 0));
-   * durationB = new Date(Date.UTC(2024, 12, 26, 13, 0, 0));
+   * durationA = new Date(Date.UTC(2024, 11, 26, 12, 0, 0));
+   * durationB = new Date(Date.UTC(2024, 11, 26, 13, 0, 0));
    * range = new utils.DateRange(durationA, durationB);
    * 
    * range.toLocaleString(); // '1/26/2025, 12:00:00 PM to 1/26/2025, 1:00:00 PM'