diff --git a/lib/node_modules/@stdlib/plot/vega/padding/ctor/README.md b/lib/node_modules/@stdlib/plot/vega/padding/ctor/README.md index 89f77bc2a798..94324833e6ca 100644 --- a/lib/node_modules/@stdlib/plot/vega/padding/ctor/README.md +++ b/lib/node_modules/@stdlib/plot/vega/padding/ctor/README.md @@ -26,6 +26,8 @@ limitations under the License.
+A padding configuration defines the spacing (in pixels) around the main chart group area. It determines the gap between the boundaries of the root visualization area and the inner rendering layout. +
@@ -47,28 +49,32 @@ Returns a padding instance. ```javascript var padding = new Padding(); // returns + +padding = new Padding({ + 'left': 80, + 'right': 80, + 'top': 80, + 'bottom': 80 +}); +// returns ``` -The constructor accepts the following `options`: + + +
+ A visualization showing padding margins around the main chart area. +
+
+ + + +The constructor accepts the following options: - **bottom**: bottom padding (in pixels). Default: `0`. - **left**: left padding (in pixels). Default: `0`. - **right**: right padding (in pixels). Default: `0`. - **top**: top padding (in pixels). Default: `0`. -```javascript -var padding = new Padding({ - 'bottom': 10, - 'left': 20, - 'right': 30, - 'top': 40 -}); -// returns - -var v = padding.top; -// returns 40 -``` - * * * ### Writable Properties @@ -77,70 +83,166 @@ var v = padding.top; #### Padding.prototype.bottom -Bottom padding (in pixels). Default: `0`. +Bottom padding (in pixels). ```javascript -var padding = new Padding(); - -// Set: -padding.bottom = 10; +var padding = new Padding({ + 'left': 80, + 'right': 80, + 'top': 80, + 'bottom': 0 +}); -// Get: var v = padding.bottom; -// returns 10 +// returns 0 + +padding.bottom = 100; + +v = padding.bottom; +// returns 100 ``` + + +
+ Padding with bottom set to 0. +
+
+ + + + + +
+ Padding with bottom set to 100. +
+
+ + + #### Padding.prototype.left -Left padding (in pixels). Default: `0`. +Left padding (in pixels). ```javascript -var padding = new Padding(); - -// Set: -padding.left = 10; +var padding = new Padding({ + 'left': 0, + 'right': 80, + 'top': 80, + 'bottom': 80 +}); -// Get: var v = padding.left; -// returns 10 +// returns 0 + +padding.left = 130; + +v = padding.left; +// returns 130 ``` + + +
+ Padding with left set to 0. +
+
+ + + + + +
+ Padding with left set to 130. +
+
+ + + #### Padding.prototype.right -Right padding (in pixels). Default: `0`. +Right padding (in pixels). ```javascript -var padding = new Padding(); - -// Set: -padding.right = 10; +var padding = new Padding({ + 'left': 80, + 'right': 0, + 'top': 80, + 'bottom': 80 +}); -// Get: var v = padding.right; -// returns 10 +// returns 0 + +padding.right = 130; + +v = padding.right; +// returns 130 ``` + + +
+ Padding with right set to 0. +
+
+ + + + + +
+ Padding with right set to 130. +
+
+ + + #### Padding.prototype.top -Top padding (in pixels). Default: `0`. +Top padding (in pixels). ```javascript -var padding = new Padding(); - -// Set: -padding.top = 10; +var padding = new Padding({ + 'left': 80, + 'right': 80, + 'top': 0, + 'bottom': 80 +}); -// Get: var v = padding.top; -// returns 10 +// returns 0 + +padding.top = 100; + +v = padding.top; +// returns 100 ``` + + +
+ Padding with top set to 0. +
+
+ + + + + +
+ Padding with top set to 100. +
+
+ + + * * * ### Read-only Properties @@ -166,15 +268,18 @@ var v = padding.properties; #### Padding.prototype.toJSON() -Serializes a padding instance to a JSON object. +Serializes an instance to a JSON representation. ```javascript var padding = new Padding({ - 'top': 10 + 'left': 80, + 'right': 80, + 'top': 80, + 'bottom': 80 }); var v = padding.toJSON(); -// returns { 'bottom': 0, 'left': 0, 'right': 0, 'top': 10 } +// returns { 'bottom': 80, 'left': 80, 'right': 80, 'top': 80 } ``` This method is implicitly invoked by `JSON.stringify`. @@ -184,7 +289,7 @@ var padding = new Padding({ 'top': 10 }); -var str = JSON.stringify( padding ); +var v = JSON.stringify( padding ); // returns '{"bottom":0,"left":0,"right":0,"top":10}' ``` diff --git a/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding.svg b/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding.svg new file mode 100644 index 000000000000..a098583ae714 --- /dev/null +++ b/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding.svg @@ -0,0 +1 @@ +left: 80pxright: 80pxtop: 80pxbottom: 80px \ No newline at end of file diff --git a/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding_bottom_0.svg b/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding_bottom_0.svg new file mode 100644 index 000000000000..f9b3d55bca04 --- /dev/null +++ b/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding_bottom_0.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding_bottom_100.svg b/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding_bottom_100.svg new file mode 100644 index 000000000000..a416d238c55f --- /dev/null +++ b/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding_bottom_100.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding_left_0.svg b/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding_left_0.svg new file mode 100644 index 000000000000..f744392e0cee --- /dev/null +++ b/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding_left_0.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding_left_130.svg b/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding_left_130.svg new file mode 100644 index 000000000000..507c5c270b11 --- /dev/null +++ b/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding_left_130.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding_right_0.svg b/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding_right_0.svg new file mode 100644 index 000000000000..edf88d3d267c --- /dev/null +++ b/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding_right_0.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding_right_130.svg b/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding_right_130.svg new file mode 100644 index 000000000000..402ab7ff846b --- /dev/null +++ b/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding_right_130.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding_top_0.svg b/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding_top_0.svg new file mode 100644 index 000000000000..b6f7610e718b --- /dev/null +++ b/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding_top_0.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding_top_100.svg b/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding_top_100.svg new file mode 100644 index 000000000000..2343aeb30d9b --- /dev/null +++ b/lib/node_modules/@stdlib/plot/vega/padding/ctor/docs/img/figure_padding_top_100.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/lib/node_modules/@stdlib/plot/vega/padding/ctor/srv/scripts/fig_padding.js b/lib/node_modules/@stdlib/plot/vega/padding/ctor/srv/scripts/fig_padding.js new file mode 100644 index 000000000000..6a19bbaac110 --- /dev/null +++ b/lib/node_modules/@stdlib/plot/vega/padding/ctor/srv/scripts/fig_padding.js @@ -0,0 +1,452 @@ +#!/usr/bin/env node + +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +/* eslint-disable max-lines, stdlib/no-unnecessary-nested-functions, n/no-sync */ + +// MODULES // + +var resolve = require( 'path' ).resolve; +var join = require( 'path' ).join; +var logger = require( 'debug' ); +var extname = require( '@stdlib/utils/extname' ); +var readdirSync = require( '@stdlib/fs/read-dir' ).sync; +var unlinkSync = require( '@stdlib/fs/unlink' ).sync; +var existsSync = require( '@stdlib/fs/exists' ).sync; +var renderFig = require( '@stdlib/plot/vega/base/spec2svg-file' ); + + +// VARIABLES // + +var debug = logger( 'vega:padding:figures' ); + +var IMG_DIR = resolve( __dirname, '..', '..', 'docs', 'img' ); +var SCHEMA = 'https://vega.github.io/schema/vega/v6.json'; +var OUTER_MARGIN = 15; +var OUTER_WIDTH = 600; +var OUTER_HEIGHT = 260; +var DEFAULT_PADDING = 80; +var LABEL_FONT_SIZE = 13; +var LABEL_FONT_WEIGHT = 'bold'; +var LABEL_FILL = '#555'; + +// Figure configuration array: +var FIGURES = [ + { + 'name': 'figure_padding', + 'padding': { + 'left': DEFAULT_PADDING, + 'right': DEFAULT_PADDING, + 'top': DEFAULT_PADDING, + 'bottom': DEFAULT_PADDING + }, + 'marks': [ + createTextLabel( 40, 130, 'left: 80px' ), + createTextLabel( 560, 130, 'right: 80px' ), + createTextLabel( 300, 40, 'top: 80px' ), + createTextLabel( 300, 220, 'bottom: 80px' ) + ] + }, + + // top: + { + 'name': 'figure_padding_top_0', + 'padding': { + 'left': DEFAULT_PADDING, + 'right': DEFAULT_PADDING, + 'top': 0, + 'bottom': DEFAULT_PADDING + } + }, + { + 'name': 'figure_padding_top_100', + 'padding': { + 'left': DEFAULT_PADDING, + 'right': DEFAULT_PADDING, + 'top': 100, + 'bottom': DEFAULT_PADDING + } + }, + + // bottom: + { + 'name': 'figure_padding_bottom_0', + 'padding': { + 'left': DEFAULT_PADDING, + 'right': DEFAULT_PADDING, + 'top': DEFAULT_PADDING, + 'bottom': 0 + } + }, + { + 'name': 'figure_padding_bottom_100', + 'padding': { + 'left': DEFAULT_PADDING, + 'right': DEFAULT_PADDING, + 'top': DEFAULT_PADDING, + 'bottom': 100 + } + }, + + // left: + { + 'name': 'figure_padding_left_0', + 'padding': { + 'left': 0, + 'right': DEFAULT_PADDING, + 'top': DEFAULT_PADDING, + 'bottom': DEFAULT_PADDING + } + }, + { + 'name': 'figure_padding_left_130', + 'padding': { + 'left': 130, + 'right': DEFAULT_PADDING, + 'top': DEFAULT_PADDING, + 'bottom': DEFAULT_PADDING + } + }, + + // right: + { + 'name': 'figure_padding_right_0', + 'padding': { + 'left': DEFAULT_PADDING, + 'right': 0, + 'top': DEFAULT_PADDING, + 'bottom': DEFAULT_PADDING + } + }, + { + 'name': 'figure_padding_right_130', + 'padding': { + 'left': DEFAULT_PADDING, + 'right': 130, + 'top': DEFAULT_PADDING, + 'bottom': DEFAULT_PADDING + } + } +]; + + +// FUNCTIONS // + +/** +* Creates a Vega text label mark definition. +* +* @private +* @param {number} x - x-coordinate +* @param {number} y - y-coordinate +* @param {string} text - label text +* @returns {Object} Vega mark definition +*/ +function createTextLabel( x, y, text ) { + return { + 'type': 'text', + 'encode': { + 'enter': { + 'x': { + 'value': x + }, + 'y': { + 'value': y + }, + 'align': { + 'value': 'center' + }, + 'baseline': { + 'value': 'middle' + }, + 'text': { + 'value': text + }, + 'fontSize': { + 'value': LABEL_FONT_SIZE + }, + 'fontWeight': { + 'value': LABEL_FONT_WEIGHT + }, + 'fill': { + 'value': LABEL_FILL + } + } + } + }; +} + +/** +* Creates a Vega rectangle mark for the outer dotted boundary. +* +* @private +* @param {number} width - outer width +* @param {number} height - outer height +* @returns {Object} Vega mark definition +*/ +function createOuterRect( width, height ) { + return { + 'type': 'rect', + 'encode': { + 'enter': { + 'x': { + 'value': 0 + }, + 'y': { + 'value': 0 + }, + 'width': { + 'value': width + }, + 'height': { + 'value': height + }, + 'stroke': { + 'value': '#aaa' + }, + 'strokeWidth': { + 'value': 1.5 + }, + 'strokeDash': { + 'value': [ 4, 4 ] + } + } + } + }; +} + +/** +* Creates a Vega rectangle mark for the inner chart area. +* +* @private +* @param {number} x - x-coordinate +* @param {number} y - y-coordinate +* @param {number} width - width +* @param {number} height - height +* @returns {Object} Vega mark definition +*/ +function createInnerRect( x, y, width, height ) { + return { + 'type': 'rect', + 'encode': { + 'enter': { + 'x': { + 'value': x + }, + 'y': { + 'value': y + }, + 'width': { + 'value': width + }, + 'height': { + 'value': height + }, + 'fill': { + 'value': '#f5f5f5' + }, + 'stroke': { + 'value': '#666' + }, + 'strokeWidth': { + 'value': 1 + } + } + } + }; +} + +/** +* Creates a Vega specification from a figure configuration. +* +* @private +* @param {Object} config - figure configuration +* @param {Object} config.padding - padding configuration +* @param {Array} [config.marks] - additional marks +* @returns {Object} Vega specification +*/ +function createSpec( config ) { + var innerHeight; + var innerWidth; + var padding; + var marks; + var spec; + var x; + var y; + + padding = config.padding; + + // Compute inner chart area dimensions based on actual padding values: + x = padding.left; + y = padding.top; + innerWidth = OUTER_WIDTH - padding.left - padding.right; + innerHeight = OUTER_HEIGHT - padding.top - padding.bottom; + + marks = [ + createOuterRect( OUTER_WIDTH, OUTER_HEIGHT ), + createInnerRect( x, y, innerWidth, innerHeight ) + ]; + if ( config.marks ) { + marks = marks.concat( config.marks ); + } + spec = { + '$schema': SCHEMA, + 'width': OUTER_WIDTH, + 'height': OUTER_HEIGHT, + 'padding': OUTER_MARGIN, + 'background': '#ffffff', + 'marks': marks + }; + return spec; +} + +/** +* Generates all figure SVGs sequentially. +* +* @private +* @param {Array} figures - figure configuration array +* @param {Callback} clbk - callback to invoke upon completion +* @returns {void} +*/ +function generateAll( figures, clbk ) { + var idx = 0; + next(); + + /** + * Processes the next figure in the queue. + * + * @private + * @returns {void} + */ + function next() { + var outputPath; + var config; + var spec; + + if ( idx >= figures.length ) { + return clbk( null ); + } + config = figures[ idx ]; + spec = createSpec( config ); + outputPath = join( IMG_DIR, config.name + '.svg' ); + + debug( 'Rendering: %s', config.name ); + renderFig( outputPath, spec, onDone ); + } + + /** + * Callback invoked upon completing a figure render. + * + * @private + * @param {(Error|null)} error - error object + * @returns {void} + */ + function onDone( error ) { + if ( error ) { + return clbk( error ); + } + debug( ' -> %s', join( IMG_DIR, figures[ idx ].name + '.svg' ) ); + idx += 1; + next(); + } +} + +/** +* Removes stale SVG files from a directory listing. +* +* @private +* @param {Array} files - directory entries +* @throws {Error} if unable to remove a stale file +* @returns {void} +*/ +function removeStaleFiles( files ) { + var valid; + var file; + var err; + var f; + var i; + var j; + + for ( i = 0; i < files.length; i++ ) { + file = files[ i ]; + if ( extname( file ) === '.svg' ) { + continue; + } + valid = false; + for ( j = 0; j < FIGURES.length; j++ ) { + f = FIGURES[ j ].name + '.svg'; + if ( file === f ) { + valid = true; + break; + } + } + if ( !valid ) { + debug( 'Removing stale SVG: %s', file ); + err = unlinkSync( join( IMG_DIR, file ) ); + if ( err instanceof Error ) { + throw err; + } + } + } +} + + +// MAIN // + +/** +* Generates all padding documentation figures. +* +* @private +* @returns {void} +*/ +function main() { + var files; + + if ( existsSync( IMG_DIR ) ) { + files = readdirSync( IMG_DIR ); + if ( files instanceof Error ) { + console.error( 'Error reading directory: %s', files.message ); // eslint-disable-line no-console + process.exitCode = 1; + return; + } + removeStaleFiles( files ); + } + + // Generate all figure SVGs: + generateAll( FIGURES, onComplete ); + + /** + * Callback invoked upon completing all figure generation. + * + * @private + * @param {(Error|null)} error - error object + * @returns {void} + */ + function onComplete( error ) { + if ( error ) { + console.error( 'Error generating figures: %s', error.message ); // eslint-disable-line no-console + process.exitCode = 1; + return; + } + console.log( 'Successfully generated %d padding figures.', FIGURES.length ); // eslint-disable-line no-console + } +} + +main();