From 0e3fb237fd7eb686bc2856065bd8b81a2cd0b44f Mon Sep 17 00:00:00 2001 From: Mark Stacey Date: Tue, 12 Oct 2021 17:48:25 -0230 Subject: [PATCH] Add JSDoc comments JSDoc comments have been added for the two functions that have been modified in this PR. --- docs/beta/bundle.js | 107 +++++++++++++++++++++++++++++++++++++++- docs/distort/bundle.js | 107 +++++++++++++++++++++++++++++++++++++++- docs/gradient/bundle.js | 107 +++++++++++++++++++++++++++++++++++++++- docs/normal/bundle.js | 107 +++++++++++++++++++++++++++++++++++++++- docs/recolor/bundle.js | 107 +++++++++++++++++++++++++++++++++++++++- util.js | 99 +++++++++++++++++++++++++++++++++++++ 6 files changed, 629 insertions(+), 5 deletions(-) diff --git a/docs/beta/bundle.js b/docs/beta/bundle.js index 0f8261e3..0bd43d7b 100644 --- a/docs/beta/bundle.js +++ b/docs/beta/bundle.js @@ -1211,6 +1211,81 @@ module.exports = { Polygon, }; +/** + * A distance measurement used for SVG attributes. A length is specified as a number followed by a + * unit identifier. + * + * See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Content_type#length} for further + * information. + * + * @typedef {`${number}${'em' | 'ex' | 'px' | 'in' | 'cm' | 'mm' | 'pt' | 'pc' | '%'}`} SvgLength + */ + +/** + * A definition for a `` SVG element, which defines a color and the position for that color + * on a gradient. This element is always a child of either a `` or + * `` element. + * + * See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element/stop} for more information + * about the `` element. + * + * @typedef {object} StopDefinition + * @property {number | `${number}%`} [offset] - The location of the gradient stop along the + * gradient vector. + * @property {string} [stop-color] - The color of the gradient stop. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element/stop}. + * @property {number} [stop-opacity] - The opacity of the gradient stop. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stop-opacity}. + */ + +/** + * A definition for a `` SVG element. This definition includes all supported + * `` attributes, and it includes a `stops` property which is an array of + * definitions for each `` child node. + * + * See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element/linearGradient} for more + * information about the `` element. + * + * @typedef {object} LinearGradientDefinition + * @property {string} [gradientTransform] - A transform from the gradient coordinate system to the + * target coordinate system. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/gradientTransform}. + * @property {'userSpaceOnUse' | 'objectBoundingBox'} [gradientUnits] - The coordinate system used. + * for the coordinate attributes. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/gradientUnits}. + * @property {'pad' | 'reflect' | 'repeat'} [spreadMethod] - The method used to fill a shape beyond + * the defined edges of a gradient. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/spreadMethod}. + * @property {StopDefinition[]} [stops] - The colors of the gradient, and the position of each + * color along the gradient vector. + * @property {'linear'} type - The type of the gradient. + * @property {SvgLength} [x1] - The x coordinate of the starting point of the vector gradient. + * @property {SvgLength} [x2] - The x coordinate of the ending point of the vector gradient. + * @property {SvgLength} [y1] - The y coordinate of the starting point of the vector gradient. + * @property {SvgLength} [y2] - The y coordinate of the ending point of the vector gradient. + */ + +/** + * A definition for a `` SVG element. This definition includes all supported + * `` attributes, and it includes a `stops` property which is an array of + * definitions for each `` child node. + * + * See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element/radialGradient} for more + * information about the `` element. + * + * @typedef {object} RadialGradientDefinition + * @property {SvgLength} [cx] - The x coordinate of the end circle of the radial gradiant. + * @property {SvgLength} [cy] - The y coordinate of the end circle of the radial gradient. + * @property {SvgLength} [fr] - The radius of the start circle of the radial gradient. + * @property {SvgLength} [fx] - The x coordinate of the start circle of the radial gradient. + * @property {SvgLength} [fy] - The y coordinate of the start circle of the radial gradient. + * @property {string} [gradientTransform] - A transform from the gradient coordinate system to the + * target coordinate system. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/gradientTransform}. + * @property {'userSpaceOnUse' | 'objectBoundingBox'} [gradientUnits] - The coordinate system used + * for the coordinate attributes. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/gradientUnits}. + * @property {SvgLength} [r] - The radius of the end circle of the radial gradient. + * @property {'pad' | 'reflect' | 'repeat'} [spreadMethod] - The method used to fill a shape beyond + * the defined edges of a gradient. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/spreadMethod}. + * @property {StopDefinition[]} [stops] - The colors of the gradient, and the position of each + * color along the gradient vector. + * @property {'radial'} type - The type of the gradient. + */ + function createLogoViewer( container, renderScene, @@ -1413,6 +1488,21 @@ function createPolygonsFromModelJson(modelJson, createSvgPolygon) { return { polygons, polygonsByChunk }; } +/** + * Create an SVG ` element. + * + * This polygon is assigned the correct `fill` and `stroke` attributes, according to the chunk + * definition provided. But the `points` attribute is always set to a dummy value, as it gets reset + * later to the correct position during each render loop. + * + * @param {object} chunk - The definition for the chunk of the model this polygon is a part of. + * This includes the color or gradient to apply to the polygon. + * @param {object} options - Polygon options. + * @param {(LinearGradientDefinition | RadialGradientDefinition)[]} [options.gradients] - The set of + * all gradient definitions used in this model. + * @param options.index - The index for the chunk this polygon is found in. + * @returns {Element} The `` SVG element. + */ function createStandardModelPolygon(chunk, { gradients = {}, index }) { const svgPolygon = createNode('polygon'); @@ -1626,6 +1716,15 @@ function Polygon(svg, indices) { this.zIndex = 0; } +/** + * Parse gradient definitions and construct them in the DOM. + * + * Both `` and `` are supported. All gradients get added to a + * `` element that is added as a direct child of the container element. + * + * @param {Element} container - The `` HTML element that the definitions should be added to. + * @param {(LinearGradientDefinition | RadialGradientDefinition)[]} [gradients] - The gradient definitions. + */ function setGradientDefinitions(container, gradients) { if (!gradients || Object.keys(gradients).length === 0) { return; @@ -1635,7 +1734,13 @@ function setGradientDefinitions(container, gradients) { const linearCoordinateAttributes = ['x1', 'x2', 'y1', 'y2']; const radialCoordinateAttributes = ['cx', 'cy', 'fr', 'fx', 'fy', 'r']; - const commonAttributes = ['gradientUnits', 'spreadMethod', 'stops', 'type']; + const commonAttributes = [ + 'gradientTransform', + 'gradientUnits', + 'spreadMethod', + 'stops', + 'type', + ]; const allLinearAttributes = [ ...linearCoordinateAttributes, ...commonAttributes, diff --git a/docs/distort/bundle.js b/docs/distort/bundle.js index 7ced2130..e212f3d6 100644 --- a/docs/distort/bundle.js +++ b/docs/distort/bundle.js @@ -828,6 +828,81 @@ module.exports = { Polygon, }; +/** + * A distance measurement used for SVG attributes. A length is specified as a number followed by a + * unit identifier. + * + * See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Content_type#length} for further + * information. + * + * @typedef {`${number}${'em' | 'ex' | 'px' | 'in' | 'cm' | 'mm' | 'pt' | 'pc' | '%'}`} SvgLength + */ + +/** + * A definition for a `` SVG element, which defines a color and the position for that color + * on a gradient. This element is always a child of either a `` or + * `` element. + * + * See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element/stop} for more information + * about the `` element. + * + * @typedef {object} StopDefinition + * @property {number | `${number}%`} [offset] - The location of the gradient stop along the + * gradient vector. + * @property {string} [stop-color] - The color of the gradient stop. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element/stop}. + * @property {number} [stop-opacity] - The opacity of the gradient stop. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stop-opacity}. + */ + +/** + * A definition for a `` SVG element. This definition includes all supported + * `` attributes, and it includes a `stops` property which is an array of + * definitions for each `` child node. + * + * See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element/linearGradient} for more + * information about the `` element. + * + * @typedef {object} LinearGradientDefinition + * @property {string} [gradientTransform] - A transform from the gradient coordinate system to the + * target coordinate system. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/gradientTransform}. + * @property {'userSpaceOnUse' | 'objectBoundingBox'} [gradientUnits] - The coordinate system used. + * for the coordinate attributes. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/gradientUnits}. + * @property {'pad' | 'reflect' | 'repeat'} [spreadMethod] - The method used to fill a shape beyond + * the defined edges of a gradient. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/spreadMethod}. + * @property {StopDefinition[]} [stops] - The colors of the gradient, and the position of each + * color along the gradient vector. + * @property {'linear'} type - The type of the gradient. + * @property {SvgLength} [x1] - The x coordinate of the starting point of the vector gradient. + * @property {SvgLength} [x2] - The x coordinate of the ending point of the vector gradient. + * @property {SvgLength} [y1] - The y coordinate of the starting point of the vector gradient. + * @property {SvgLength} [y2] - The y coordinate of the ending point of the vector gradient. + */ + +/** + * A definition for a `` SVG element. This definition includes all supported + * `` attributes, and it includes a `stops` property which is an array of + * definitions for each `` child node. + * + * See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element/radialGradient} for more + * information about the `` element. + * + * @typedef {object} RadialGradientDefinition + * @property {SvgLength} [cx] - The x coordinate of the end circle of the radial gradiant. + * @property {SvgLength} [cy] - The y coordinate of the end circle of the radial gradient. + * @property {SvgLength} [fr] - The radius of the start circle of the radial gradient. + * @property {SvgLength} [fx] - The x coordinate of the start circle of the radial gradient. + * @property {SvgLength} [fy] - The y coordinate of the start circle of the radial gradient. + * @property {string} [gradientTransform] - A transform from the gradient coordinate system to the + * target coordinate system. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/gradientTransform}. + * @property {'userSpaceOnUse' | 'objectBoundingBox'} [gradientUnits] - The coordinate system used + * for the coordinate attributes. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/gradientUnits}. + * @property {SvgLength} [r] - The radius of the end circle of the radial gradient. + * @property {'pad' | 'reflect' | 'repeat'} [spreadMethod] - The method used to fill a shape beyond + * the defined edges of a gradient. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/spreadMethod}. + * @property {StopDefinition[]} [stops] - The colors of the gradient, and the position of each + * color along the gradient vector. + * @property {'radial'} type - The type of the gradient. + */ + function createLogoViewer( container, renderScene, @@ -1030,6 +1105,21 @@ function createPolygonsFromModelJson(modelJson, createSvgPolygon) { return { polygons, polygonsByChunk }; } +/** + * Create an SVG ` element. + * + * This polygon is assigned the correct `fill` and `stroke` attributes, according to the chunk + * definition provided. But the `points` attribute is always set to a dummy value, as it gets reset + * later to the correct position during each render loop. + * + * @param {object} chunk - The definition for the chunk of the model this polygon is a part of. + * This includes the color or gradient to apply to the polygon. + * @param {object} options - Polygon options. + * @param {(LinearGradientDefinition | RadialGradientDefinition)[]} [options.gradients] - The set of + * all gradient definitions used in this model. + * @param options.index - The index for the chunk this polygon is found in. + * @returns {Element} The `` SVG element. + */ function createStandardModelPolygon(chunk, { gradients = {}, index }) { const svgPolygon = createNode('polygon'); @@ -1243,6 +1333,15 @@ function Polygon(svg, indices) { this.zIndex = 0; } +/** + * Parse gradient definitions and construct them in the DOM. + * + * Both `` and `` are supported. All gradients get added to a + * `` element that is added as a direct child of the container element. + * + * @param {Element} container - The `` HTML element that the definitions should be added to. + * @param {(LinearGradientDefinition | RadialGradientDefinition)[]} [gradients] - The gradient definitions. + */ function setGradientDefinitions(container, gradients) { if (!gradients || Object.keys(gradients).length === 0) { return; @@ -1252,7 +1351,13 @@ function setGradientDefinitions(container, gradients) { const linearCoordinateAttributes = ['x1', 'x2', 'y1', 'y2']; const radialCoordinateAttributes = ['cx', 'cy', 'fr', 'fx', 'fy', 'r']; - const commonAttributes = ['gradientUnits', 'spreadMethod', 'stops', 'type']; + const commonAttributes = [ + 'gradientTransform', + 'gradientUnits', + 'spreadMethod', + 'stops', + 'type', + ]; const allLinearAttributes = [ ...linearCoordinateAttributes, ...commonAttributes, diff --git a/docs/gradient/bundle.js b/docs/gradient/bundle.js index df55e1fa..dc750a03 100644 --- a/docs/gradient/bundle.js +++ b/docs/gradient/bundle.js @@ -1211,6 +1211,81 @@ module.exports = { Polygon, }; +/** + * A distance measurement used for SVG attributes. A length is specified as a number followed by a + * unit identifier. + * + * See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Content_type#length} for further + * information. + * + * @typedef {`${number}${'em' | 'ex' | 'px' | 'in' | 'cm' | 'mm' | 'pt' | 'pc' | '%'}`} SvgLength + */ + +/** + * A definition for a `` SVG element, which defines a color and the position for that color + * on a gradient. This element is always a child of either a `` or + * `` element. + * + * See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element/stop} for more information + * about the `` element. + * + * @typedef {object} StopDefinition + * @property {number | `${number}%`} [offset] - The location of the gradient stop along the + * gradient vector. + * @property {string} [stop-color] - The color of the gradient stop. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element/stop}. + * @property {number} [stop-opacity] - The opacity of the gradient stop. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stop-opacity}. + */ + +/** + * A definition for a `` SVG element. This definition includes all supported + * `` attributes, and it includes a `stops` property which is an array of + * definitions for each `` child node. + * + * See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element/linearGradient} for more + * information about the `` element. + * + * @typedef {object} LinearGradientDefinition + * @property {string} [gradientTransform] - A transform from the gradient coordinate system to the + * target coordinate system. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/gradientTransform}. + * @property {'userSpaceOnUse' | 'objectBoundingBox'} [gradientUnits] - The coordinate system used. + * for the coordinate attributes. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/gradientUnits}. + * @property {'pad' | 'reflect' | 'repeat'} [spreadMethod] - The method used to fill a shape beyond + * the defined edges of a gradient. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/spreadMethod}. + * @property {StopDefinition[]} [stops] - The colors of the gradient, and the position of each + * color along the gradient vector. + * @property {'linear'} type - The type of the gradient. + * @property {SvgLength} [x1] - The x coordinate of the starting point of the vector gradient. + * @property {SvgLength} [x2] - The x coordinate of the ending point of the vector gradient. + * @property {SvgLength} [y1] - The y coordinate of the starting point of the vector gradient. + * @property {SvgLength} [y2] - The y coordinate of the ending point of the vector gradient. + */ + +/** + * A definition for a `` SVG element. This definition includes all supported + * `` attributes, and it includes a `stops` property which is an array of + * definitions for each `` child node. + * + * See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element/radialGradient} for more + * information about the `` element. + * + * @typedef {object} RadialGradientDefinition + * @property {SvgLength} [cx] - The x coordinate of the end circle of the radial gradiant. + * @property {SvgLength} [cy] - The y coordinate of the end circle of the radial gradient. + * @property {SvgLength} [fr] - The radius of the start circle of the radial gradient. + * @property {SvgLength} [fx] - The x coordinate of the start circle of the radial gradient. + * @property {SvgLength} [fy] - The y coordinate of the start circle of the radial gradient. + * @property {string} [gradientTransform] - A transform from the gradient coordinate system to the + * target coordinate system. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/gradientTransform}. + * @property {'userSpaceOnUse' | 'objectBoundingBox'} [gradientUnits] - The coordinate system used + * for the coordinate attributes. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/gradientUnits}. + * @property {SvgLength} [r] - The radius of the end circle of the radial gradient. + * @property {'pad' | 'reflect' | 'repeat'} [spreadMethod] - The method used to fill a shape beyond + * the defined edges of a gradient. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/spreadMethod}. + * @property {StopDefinition[]} [stops] - The colors of the gradient, and the position of each + * color along the gradient vector. + * @property {'radial'} type - The type of the gradient. + */ + function createLogoViewer( container, renderScene, @@ -1413,6 +1488,21 @@ function createPolygonsFromModelJson(modelJson, createSvgPolygon) { return { polygons, polygonsByChunk }; } +/** + * Create an SVG ` element. + * + * This polygon is assigned the correct `fill` and `stroke` attributes, according to the chunk + * definition provided. But the `points` attribute is always set to a dummy value, as it gets reset + * later to the correct position during each render loop. + * + * @param {object} chunk - The definition for the chunk of the model this polygon is a part of. + * This includes the color or gradient to apply to the polygon. + * @param {object} options - Polygon options. + * @param {(LinearGradientDefinition | RadialGradientDefinition)[]} [options.gradients] - The set of + * all gradient definitions used in this model. + * @param options.index - The index for the chunk this polygon is found in. + * @returns {Element} The `` SVG element. + */ function createStandardModelPolygon(chunk, { gradients = {}, index }) { const svgPolygon = createNode('polygon'); @@ -1626,6 +1716,15 @@ function Polygon(svg, indices) { this.zIndex = 0; } +/** + * Parse gradient definitions and construct them in the DOM. + * + * Both `` and `` are supported. All gradients get added to a + * `` element that is added as a direct child of the container element. + * + * @param {Element} container - The `` HTML element that the definitions should be added to. + * @param {(LinearGradientDefinition | RadialGradientDefinition)[]} [gradients] - The gradient definitions. + */ function setGradientDefinitions(container, gradients) { if (!gradients || Object.keys(gradients).length === 0) { return; @@ -1635,7 +1734,13 @@ function setGradientDefinitions(container, gradients) { const linearCoordinateAttributes = ['x1', 'x2', 'y1', 'y2']; const radialCoordinateAttributes = ['cx', 'cy', 'fr', 'fx', 'fy', 'r']; - const commonAttributes = ['gradientUnits', 'spreadMethod', 'stops', 'type']; + const commonAttributes = [ + 'gradientTransform', + 'gradientUnits', + 'spreadMethod', + 'stops', + 'type', + ]; const allLinearAttributes = [ ...linearCoordinateAttributes, ...commonAttributes, diff --git a/docs/normal/bundle.js b/docs/normal/bundle.js index e7db1cfd..6e54b6de 100644 --- a/docs/normal/bundle.js +++ b/docs/normal/bundle.js @@ -870,6 +870,81 @@ module.exports = { Polygon, }; +/** + * A distance measurement used for SVG attributes. A length is specified as a number followed by a + * unit identifier. + * + * See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Content_type#length} for further + * information. + * + * @typedef {`${number}${'em' | 'ex' | 'px' | 'in' | 'cm' | 'mm' | 'pt' | 'pc' | '%'}`} SvgLength + */ + +/** + * A definition for a `` SVG element, which defines a color and the position for that color + * on a gradient. This element is always a child of either a `` or + * `` element. + * + * See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element/stop} for more information + * about the `` element. + * + * @typedef {object} StopDefinition + * @property {number | `${number}%`} [offset] - The location of the gradient stop along the + * gradient vector. + * @property {string} [stop-color] - The color of the gradient stop. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element/stop}. + * @property {number} [stop-opacity] - The opacity of the gradient stop. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stop-opacity}. + */ + +/** + * A definition for a `` SVG element. This definition includes all supported + * `` attributes, and it includes a `stops` property which is an array of + * definitions for each `` child node. + * + * See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element/linearGradient} for more + * information about the `` element. + * + * @typedef {object} LinearGradientDefinition + * @property {string} [gradientTransform] - A transform from the gradient coordinate system to the + * target coordinate system. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/gradientTransform}. + * @property {'userSpaceOnUse' | 'objectBoundingBox'} [gradientUnits] - The coordinate system used. + * for the coordinate attributes. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/gradientUnits}. + * @property {'pad' | 'reflect' | 'repeat'} [spreadMethod] - The method used to fill a shape beyond + * the defined edges of a gradient. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/spreadMethod}. + * @property {StopDefinition[]} [stops] - The colors of the gradient, and the position of each + * color along the gradient vector. + * @property {'linear'} type - The type of the gradient. + * @property {SvgLength} [x1] - The x coordinate of the starting point of the vector gradient. + * @property {SvgLength} [x2] - The x coordinate of the ending point of the vector gradient. + * @property {SvgLength} [y1] - The y coordinate of the starting point of the vector gradient. + * @property {SvgLength} [y2] - The y coordinate of the ending point of the vector gradient. + */ + +/** + * A definition for a `` SVG element. This definition includes all supported + * `` attributes, and it includes a `stops` property which is an array of + * definitions for each `` child node. + * + * See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element/radialGradient} for more + * information about the `` element. + * + * @typedef {object} RadialGradientDefinition + * @property {SvgLength} [cx] - The x coordinate of the end circle of the radial gradiant. + * @property {SvgLength} [cy] - The y coordinate of the end circle of the radial gradient. + * @property {SvgLength} [fr] - The radius of the start circle of the radial gradient. + * @property {SvgLength} [fx] - The x coordinate of the start circle of the radial gradient. + * @property {SvgLength} [fy] - The y coordinate of the start circle of the radial gradient. + * @property {string} [gradientTransform] - A transform from the gradient coordinate system to the + * target coordinate system. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/gradientTransform}. + * @property {'userSpaceOnUse' | 'objectBoundingBox'} [gradientUnits] - The coordinate system used + * for the coordinate attributes. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/gradientUnits}. + * @property {SvgLength} [r] - The radius of the end circle of the radial gradient. + * @property {'pad' | 'reflect' | 'repeat'} [spreadMethod] - The method used to fill a shape beyond + * the defined edges of a gradient. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/spreadMethod}. + * @property {StopDefinition[]} [stops] - The colors of the gradient, and the position of each + * color along the gradient vector. + * @property {'radial'} type - The type of the gradient. + */ + function createLogoViewer( container, renderScene, @@ -1072,6 +1147,21 @@ function createPolygonsFromModelJson(modelJson, createSvgPolygon) { return { polygons, polygonsByChunk }; } +/** + * Create an SVG ` element. + * + * This polygon is assigned the correct `fill` and `stroke` attributes, according to the chunk + * definition provided. But the `points` attribute is always set to a dummy value, as it gets reset + * later to the correct position during each render loop. + * + * @param {object} chunk - The definition for the chunk of the model this polygon is a part of. + * This includes the color or gradient to apply to the polygon. + * @param {object} options - Polygon options. + * @param {(LinearGradientDefinition | RadialGradientDefinition)[]} [options.gradients] - The set of + * all gradient definitions used in this model. + * @param options.index - The index for the chunk this polygon is found in. + * @returns {Element} The `` SVG element. + */ function createStandardModelPolygon(chunk, { gradients = {}, index }) { const svgPolygon = createNode('polygon'); @@ -1285,6 +1375,15 @@ function Polygon(svg, indices) { this.zIndex = 0; } +/** + * Parse gradient definitions and construct them in the DOM. + * + * Both `` and `` are supported. All gradients get added to a + * `` element that is added as a direct child of the container element. + * + * @param {Element} container - The `` HTML element that the definitions should be added to. + * @param {(LinearGradientDefinition | RadialGradientDefinition)[]} [gradients] - The gradient definitions. + */ function setGradientDefinitions(container, gradients) { if (!gradients || Object.keys(gradients).length === 0) { return; @@ -1294,7 +1393,13 @@ function setGradientDefinitions(container, gradients) { const linearCoordinateAttributes = ['x1', 'x2', 'y1', 'y2']; const radialCoordinateAttributes = ['cx', 'cy', 'fr', 'fx', 'fy', 'r']; - const commonAttributes = ['gradientUnits', 'spreadMethod', 'stops', 'type']; + const commonAttributes = [ + 'gradientTransform', + 'gradientUnits', + 'spreadMethod', + 'stops', + 'type', + ]; const allLinearAttributes = [ ...linearCoordinateAttributes, ...commonAttributes, diff --git a/docs/recolor/bundle.js b/docs/recolor/bundle.js index 9a113960..ae148efb 100644 --- a/docs/recolor/bundle.js +++ b/docs/recolor/bundle.js @@ -1033,6 +1033,81 @@ module.exports = { Polygon, }; +/** + * A distance measurement used for SVG attributes. A length is specified as a number followed by a + * unit identifier. + * + * See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Content_type#length} for further + * information. + * + * @typedef {`${number}${'em' | 'ex' | 'px' | 'in' | 'cm' | 'mm' | 'pt' | 'pc' | '%'}`} SvgLength + */ + +/** + * A definition for a `` SVG element, which defines a color and the position for that color + * on a gradient. This element is always a child of either a `` or + * `` element. + * + * See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element/stop} for more information + * about the `` element. + * + * @typedef {object} StopDefinition + * @property {number | `${number}%`} [offset] - The location of the gradient stop along the + * gradient vector. + * @property {string} [stop-color] - The color of the gradient stop. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element/stop}. + * @property {number} [stop-opacity] - The opacity of the gradient stop. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stop-opacity}. + */ + +/** + * A definition for a `` SVG element. This definition includes all supported + * `` attributes, and it includes a `stops` property which is an array of + * definitions for each `` child node. + * + * See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element/linearGradient} for more + * information about the `` element. + * + * @typedef {object} LinearGradientDefinition + * @property {string} [gradientTransform] - A transform from the gradient coordinate system to the + * target coordinate system. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/gradientTransform}. + * @property {'userSpaceOnUse' | 'objectBoundingBox'} [gradientUnits] - The coordinate system used. + * for the coordinate attributes. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/gradientUnits}. + * @property {'pad' | 'reflect' | 'repeat'} [spreadMethod] - The method used to fill a shape beyond + * the defined edges of a gradient. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/spreadMethod}. + * @property {StopDefinition[]} [stops] - The colors of the gradient, and the position of each + * color along the gradient vector. + * @property {'linear'} type - The type of the gradient. + * @property {SvgLength} [x1] - The x coordinate of the starting point of the vector gradient. + * @property {SvgLength} [x2] - The x coordinate of the ending point of the vector gradient. + * @property {SvgLength} [y1] - The y coordinate of the starting point of the vector gradient. + * @property {SvgLength} [y2] - The y coordinate of the ending point of the vector gradient. + */ + +/** + * A definition for a `` SVG element. This definition includes all supported + * `` attributes, and it includes a `stops` property which is an array of + * definitions for each `` child node. + * + * See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element/radialGradient} for more + * information about the `` element. + * + * @typedef {object} RadialGradientDefinition + * @property {SvgLength} [cx] - The x coordinate of the end circle of the radial gradiant. + * @property {SvgLength} [cy] - The y coordinate of the end circle of the radial gradient. + * @property {SvgLength} [fr] - The radius of the start circle of the radial gradient. + * @property {SvgLength} [fx] - The x coordinate of the start circle of the radial gradient. + * @property {SvgLength} [fy] - The y coordinate of the start circle of the radial gradient. + * @property {string} [gradientTransform] - A transform from the gradient coordinate system to the + * target coordinate system. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/gradientTransform}. + * @property {'userSpaceOnUse' | 'objectBoundingBox'} [gradientUnits] - The coordinate system used + * for the coordinate attributes. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/gradientUnits}. + * @property {SvgLength} [r] - The radius of the end circle of the radial gradient. + * @property {'pad' | 'reflect' | 'repeat'} [spreadMethod] - The method used to fill a shape beyond + * the defined edges of a gradient. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/spreadMethod}. + * @property {StopDefinition[]} [stops] - The colors of the gradient, and the position of each + * color along the gradient vector. + * @property {'radial'} type - The type of the gradient. + */ + function createLogoViewer( container, renderScene, @@ -1235,6 +1310,21 @@ function createPolygonsFromModelJson(modelJson, createSvgPolygon) { return { polygons, polygonsByChunk }; } +/** + * Create an SVG ` element. + * + * This polygon is assigned the correct `fill` and `stroke` attributes, according to the chunk + * definition provided. But the `points` attribute is always set to a dummy value, as it gets reset + * later to the correct position during each render loop. + * + * @param {object} chunk - The definition for the chunk of the model this polygon is a part of. + * This includes the color or gradient to apply to the polygon. + * @param {object} options - Polygon options. + * @param {(LinearGradientDefinition | RadialGradientDefinition)[]} [options.gradients] - The set of + * all gradient definitions used in this model. + * @param options.index - The index for the chunk this polygon is found in. + * @returns {Element} The `` SVG element. + */ function createStandardModelPolygon(chunk, { gradients = {}, index }) { const svgPolygon = createNode('polygon'); @@ -1448,6 +1538,15 @@ function Polygon(svg, indices) { this.zIndex = 0; } +/** + * Parse gradient definitions and construct them in the DOM. + * + * Both `` and `` are supported. All gradients get added to a + * `` element that is added as a direct child of the container element. + * + * @param {Element} container - The `` HTML element that the definitions should be added to. + * @param {(LinearGradientDefinition | RadialGradientDefinition)[]} [gradients] - The gradient definitions. + */ function setGradientDefinitions(container, gradients) { if (!gradients || Object.keys(gradients).length === 0) { return; @@ -1457,7 +1556,13 @@ function setGradientDefinitions(container, gradients) { const linearCoordinateAttributes = ['x1', 'x2', 'y1', 'y2']; const radialCoordinateAttributes = ['cx', 'cy', 'fr', 'fx', 'fy', 'r']; - const commonAttributes = ['gradientUnits', 'spreadMethod', 'stops', 'type']; + const commonAttributes = [ + 'gradientTransform', + 'gradientUnits', + 'spreadMethod', + 'stops', + 'type', + ]; const allLinearAttributes = [ ...linearCoordinateAttributes, ...commonAttributes, diff --git a/util.js b/util.js index 48c3db05..027af70d 100644 --- a/util.js +++ b/util.js @@ -25,6 +25,81 @@ module.exports = { Polygon, }; +/** + * A distance measurement used for SVG attributes. A length is specified as a number followed by a + * unit identifier. + * + * See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Content_type#length} for further + * information. + * + * @typedef {`${number}${'em' | 'ex' | 'px' | 'in' | 'cm' | 'mm' | 'pt' | 'pc' | '%'}`} SvgLength + */ + +/** + * A definition for a `` SVG element, which defines a color and the position for that color + * on a gradient. This element is always a child of either a `` or + * `` element. + * + * See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element/stop} for more information + * about the `` element. + * + * @typedef {object} StopDefinition + * @property {number | `${number}%`} [offset] - The location of the gradient stop along the + * gradient vector. + * @property {string} [stop-color] - The color of the gradient stop. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element/stop}. + * @property {number} [stop-opacity] - The opacity of the gradient stop. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/stop-opacity}. + */ + +/** + * A definition for a `` SVG element. This definition includes all supported + * `` attributes, and it includes a `stops` property which is an array of + * definitions for each `` child node. + * + * See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element/linearGradient} for more + * information about the `` element. + * + * @typedef {object} LinearGradientDefinition + * @property {string} [gradientTransform] - A transform from the gradient coordinate system to the + * target coordinate system. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/gradientTransform}. + * @property {'userSpaceOnUse' | 'objectBoundingBox'} [gradientUnits] - The coordinate system used. + * for the coordinate attributes. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/gradientUnits}. + * @property {'pad' | 'reflect' | 'repeat'} [spreadMethod] - The method used to fill a shape beyond + * the defined edges of a gradient. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/spreadMethod}. + * @property {StopDefinition[]} [stops] - The colors of the gradient, and the position of each + * color along the gradient vector. + * @property {'linear'} type - The type of the gradient. + * @property {SvgLength} [x1] - The x coordinate of the starting point of the vector gradient. + * @property {SvgLength} [x2] - The x coordinate of the ending point of the vector gradient. + * @property {SvgLength} [y1] - The y coordinate of the starting point of the vector gradient. + * @property {SvgLength} [y2] - The y coordinate of the ending point of the vector gradient. + */ + +/** + * A definition for a `` SVG element. This definition includes all supported + * `` attributes, and it includes a `stops` property which is an array of + * definitions for each `` child node. + * + * See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Element/radialGradient} for more + * information about the `` element. + * + * @typedef {object} RadialGradientDefinition + * @property {SvgLength} [cx] - The x coordinate of the end circle of the radial gradiant. + * @property {SvgLength} [cy] - The y coordinate of the end circle of the radial gradient. + * @property {SvgLength} [fr] - The radius of the start circle of the radial gradient. + * @property {SvgLength} [fx] - The x coordinate of the start circle of the radial gradient. + * @property {SvgLength} [fy] - The y coordinate of the start circle of the radial gradient. + * @property {string} [gradientTransform] - A transform from the gradient coordinate system to the + * target coordinate system. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/gradientTransform}. + * @property {'userSpaceOnUse' | 'objectBoundingBox'} [gradientUnits] - The coordinate system used + * for the coordinate attributes. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/gradientUnits}. + * @property {SvgLength} [r] - The radius of the end circle of the radial gradient. + * @property {'pad' | 'reflect' | 'repeat'} [spreadMethod] - The method used to fill a shape beyond + * the defined edges of a gradient. See {@link https://developer.mozilla.org/en-US/docs/Web/SVG/Attribute/spreadMethod}. + * @property {StopDefinition[]} [stops] - The colors of the gradient, and the position of each + * color along the gradient vector. + * @property {'radial'} type - The type of the gradient. + */ + function createLogoViewer( container, renderScene, @@ -227,6 +302,21 @@ function createPolygonsFromModelJson(modelJson, createSvgPolygon) { return { polygons, polygonsByChunk }; } +/** + * Create an SVG ` element. + * + * This polygon is assigned the correct `fill` and `stroke` attributes, according to the chunk + * definition provided. But the `points` attribute is always set to a dummy value, as it gets reset + * later to the correct position during each render loop. + * + * @param {object} chunk - The definition for the chunk of the model this polygon is a part of. + * This includes the color or gradient to apply to the polygon. + * @param {object} options - Polygon options. + * @param {(LinearGradientDefinition | RadialGradientDefinition)[]} [options.gradients] - The set of + * all gradient definitions used in this model. + * @param options.index - The index for the chunk this polygon is found in. + * @returns {Element} The `` SVG element. + */ function createStandardModelPolygon(chunk, { gradients = {}, index }) { const svgPolygon = createNode('polygon'); @@ -440,6 +530,15 @@ function Polygon(svg, indices) { this.zIndex = 0; } +/** + * Parse gradient definitions and construct them in the DOM. + * + * Both `` and `` are supported. All gradients get added to a + * `` element that is added as a direct child of the container element. + * + * @param {Element} container - The `` HTML element that the definitions should be added to. + * @param {(LinearGradientDefinition | RadialGradientDefinition)[]} [gradients] - The gradient definitions. + */ function setGradientDefinitions(container, gradients) { if (!gradients || Object.keys(gradients).length === 0) { return;