From d8390d210db330b32938f0036dd02234d49e1dec Mon Sep 17 00:00:00 2001 From: Peter Beshai Date: Wed, 31 Aug 2022 11:12:54 -0700 Subject: [PATCH] docs: try to improve jsdoc types --- docs/d3-interpolate-path.js | 63 +++++++++++++++++++++++++++++++------ src/interpolatePath.js | 32 ++++++++++--------- 2 files changed, 72 insertions(+), 23 deletions(-) diff --git a/docs/d3-interpolate-path.js b/docs/d3-interpolate-path.js index f59e251..7d31297 100644 --- a/docs/d3-interpolate-path.js +++ b/docs/d3-interpolate-path.js @@ -42,6 +42,22 @@ function _objectSpread2(target) { return target; } +function _typeof(obj) { + "@babel/helpers - typeof"; + + if (typeof Symbol === "function" && typeof Symbol.iterator === "symbol") { + _typeof = function (obj) { + return typeof obj; + }; + } else { + _typeof = function (obj) { + return obj && typeof Symbol === "function" && obj.constructor === Symbol && obj !== Symbol.prototype ? "symbol" : typeof obj; + }; + } + + return _typeof(obj); +} + function _defineProperty(obj, key, value) { if (key in obj) { Object.defineProperty(obj, key, { @@ -568,15 +584,26 @@ function pathCommandsFromString(d) { * * @param {Object[]} aCommandsInput Array of path commands * @param {Object[]} bCommandsInput Array of path commands - * @param {Function} excludeSegment a function that takes a start command object and + * @param {(Function|Object)} interpolateOptions + * @param {Function} interpolateOptions.excludeSegment a function that takes a start command object and * end command object and returns true if the segment should be excluded from splitting. + * @param {Boolean} interpolateOptions.snapEndsToInput a boolean indicating whether end of input should + * be sourced from input argument or computed. * @returns {Function} Interpolation function that maps t ([0, 1]) to an array of path commands. */ -function interpolatePathCommands(aCommandsInput, bCommandsInput, excludeSegment) { +function interpolatePathCommands(aCommandsInput, bCommandsInput, interpolateOptions) { // make a copy so we don't mess with the input arrays var aCommands = aCommandsInput == null ? [] : aCommandsInput.slice(); - var bCommands = bCommandsInput == null ? [] : bCommandsInput.slice(); // both input sets are empty, so we don't interpolate + var bCommands = bCommandsInput == null ? [] : bCommandsInput.slice(); + + var _ref = _typeof(interpolateOptions) === 'object' ? interpolateOptions : { + excludeSegment: interpolateOptions, + snapEndsToInput: true + }, + excludeSegment = _ref.excludeSegment, + snapEndsToInput = _ref.snapEndsToInput; // both input sets are empty, so we don't interpolate + if (!aCommands.length && !bCommands.length) { return function nullInterpolator() { @@ -637,7 +664,7 @@ function interpolatePathCommands(aCommandsInput, bCommandsInput, excludeSegment) return function pathCommandInterpolator(t) { // at 1 return the final value without the extensions used during interpolation - if (t === 1) { + if (t === 1 && snapEndsToInput) { return bCommandsInput == null ? [] : bCommandsInput; } // work with aCommands directly since interpolatedCommands are mutated @@ -675,6 +702,8 @@ function interpolatePathCommands(aCommandsInput, bCommandsInput, excludeSegment) return interpolatedCommands; }; } +/** @typedef InterpolateOptions */ + /** * Interpolate from A to B by extending A and B during interpolation to have * the same number of points. This allows for a smooth transition when they @@ -684,25 +713,41 @@ function interpolatePathCommands(aCommandsInput, bCommandsInput, excludeSegment) * * @param {String} a The `d` attribute for a path * @param {String} b The `d` attribute for a path - * @param {Function} excludeSegment a function that takes a start command object and - * end command object and returns true if the segment should be excluded from splitting. + * @param {((command1, command2) => boolean|{ + * excludeSegment?: (command1, command2) => boolean; + * snapEndsToInput?: boolean + * })} interpolateOptions The excludeSegment function or an options object + * - interpolateOptions.excludeSegment a function that takes a start command object and + * end command object and returns true if the segment should be excluded from splitting. + * - interpolateOptions.snapEndsToInput a boolean indicating whether end of input should + * be sourced from input argument or computed. * @returns {Function} Interpolation function that maps t ([0, 1]) to a path `d` string. */ -function interpolatePath(a, b, excludeSegment) { +function interpolatePath(a, b, interpolateOptions) { var aCommands = pathCommandsFromString(a); var bCommands = pathCommandsFromString(b); + var _ref2 = _typeof(interpolateOptions) === 'object' ? interpolateOptions : { + excludeSegment: interpolateOptions, + snapEndsToInput: true + }, + excludeSegment = _ref2.excludeSegment, + snapEndsToInput = _ref2.snapEndsToInput; + if (!aCommands.length && !bCommands.length) { return function nullInterpolator() { return ''; }; } - var commandInterpolator = interpolatePathCommands(aCommands, bCommands, excludeSegment); + var commandInterpolator = interpolatePathCommands(aCommands, bCommands, { + excludeSegment: excludeSegment, + snapEndsToInput: snapEndsToInput + }); return function pathStringInterpolator(t) { // at 1 return the final value without the extensions used during interpolation - if (t === 1) { + if (t === 1 && snapEndsToInput) { return b == null ? '' : b; } diff --git a/src/interpolatePath.js b/src/interpolatePath.js index e46c61b..bd3c670 100644 --- a/src/interpolatePath.js +++ b/src/interpolatePath.js @@ -314,7 +314,7 @@ export function pathCommandsFromString(d) { * @param {Function} interpolateOptions.excludeSegment a function that takes a start command object and * end command object and returns true if the segment should be excluded from splitting. * @param {Boolean} interpolateOptions.snapEndsToInput a boolean indicating whether end of input should - * be sourced from input argument or computed. + * be sourced from input argument or computed. * @returns {Function} Interpolation function that maps t ([0, 1]) to an array of path commands. */ export function interpolatePathCommands( @@ -327,7 +327,7 @@ export function interpolatePathCommands( let bCommands = bCommandsInput == null ? [] : bCommandsInput.slice(); const { excludeSegment, snapEndsToInput } = - typeof interpolateOptions === "object" + typeof interpolateOptions === 'object' ? interpolateOptions : { excludeSegment: interpolateOptions, @@ -425,6 +425,8 @@ export function interpolatePathCommands( }; } +/** @typedef InterpolateOptions */ + /** * Interpolate from A to B by extending A and B during interpolation to have * the same number of points. This allows for a smooth transition when they @@ -434,11 +436,14 @@ export function interpolatePathCommands( * * @param {String} a The `d` attribute for a path * @param {String} b The `d` attribute for a path - * @param {(Function|Object)} interpolateOptions - * @param {Function} interpolateOptions.excludeSegment a function that takes a start command object and - * end command object and returns true if the segment should be excluded from splitting. - * @param {Boolean} interpolateOptions.snapEndsToInput a boolean indicating whether end of input should - * be sourced from input argument or computed. + * @param {((command1, command2) => boolean|{ + * excludeSegment?: (command1, command2) => boolean; + * snapEndsToInput?: boolean + * })} interpolateOptions The excludeSegment function or an options object + * - interpolateOptions.excludeSegment a function that takes a start command object and + * end command object and returns true if the segment should be excluded from splitting. + * - interpolateOptions.snapEndsToInput a boolean indicating whether end of input should + * be sourced from input argument or computed. * @returns {Function} Interpolation function that maps t ([0, 1]) to a path `d` string. */ export default function interpolatePath(a, b, interpolateOptions) { @@ -446,7 +451,7 @@ export default function interpolatePath(a, b, interpolateOptions) { let bCommands = pathCommandsFromString(b); const { excludeSegment, snapEndsToInput } = - typeof interpolateOptions === "object" + typeof interpolateOptions === 'object' ? interpolateOptions : { excludeSegment: interpolateOptions, @@ -459,16 +464,15 @@ export default function interpolatePath(a, b, interpolateOptions) { }; } - const commandInterpolator = interpolatePathCommands( - aCommands, - bCommands, - { excludeSegment, snapEndsToInput } - ); + const commandInterpolator = interpolatePathCommands(aCommands, bCommands, { + excludeSegment, + snapEndsToInput, + }); return function pathStringInterpolator(t) { // at 1 return the final value without the extensions used during interpolation if (t === 1 && snapEndsToInput) { - return b == null ? "" : b; + return b == null ? '' : b; } const interpolatedCommands = commandInterpolator(t);