diff --git a/lib/node_modules/@stdlib/plot/vega/padding/ctor/README.md b/lib/node_modules/@stdlib/plot/vega/padding/ctor/README.md new file mode 100644 index 000000000000..f2fdd6950ffb --- /dev/null +++ b/lib/node_modules/@stdlib/plot/vega/padding/ctor/README.md @@ -0,0 +1,330 @@ + + +# Padding + +> [Padding][@stdlib/plot/vega/padding] constructor. + +
+ +The [padding][@stdlib/plot/vega/padding] directive 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. + +
+ + + +
+ +## Usage + +```javascript +var Padding = require( '@stdlib/plot/vega/padding/ctor' ); +``` + +#### Padding( \[options] ) + +Returns a `Padding` instance. + +```javascript +var padding = new Padding(); +// returns + +padding = new Padding({ + 'left': 80, + 'right': 80, + 'top': 80, + 'bottom': 80 +}); +// returns +``` + + + +
+ A visualization showing padding margins around the main chart area. +
+
+ + + +The `options` object has the following properties: + +- **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`. + +* * * + +### Methods + + + +#### Padding.prototype.toJSON() + +Serializes an instance to a JSON representation. + +```javascript +var padding = new Padding({ + 'left': 80, + 'right': 80, + 'top': 80, + 'bottom': 80 +}); + +var json = padding.toJSON(); +// returns { 'left': 80, 'right': 80, 'top': 80, 'bottom': 80 } +``` + +This method is implicitly invoked by `JSON.stringify`. + +* * * + +### Writable Properties + + + +#### Padding.prototype.top + +Top padding (in pixels). + +```javascript +var padding = new Padding({ + 'left': 80, + 'right': 80, + 'top': 0, + 'bottom': 80 +}); + +var v = padding.top; +// returns 0 + +padding.top = 100; + +v = padding.top; +// returns 100 +``` + + + +
+ Padding with top set to 0. +
+
+ + + + + +
+ Padding with top set to 100. +
+
+ + + + + +#### Padding.prototype.bottom + +Bottom padding (in pixels). + +```javascript +var padding = new Padding({ + 'left': 80, + 'right': 80, + 'top': 80, + 'bottom': 0 +}); + +var v = padding.bottom; +// 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). + +```javascript +var padding = new Padding({ + 'left': 0, + 'right': 80, + 'top': 80, + 'bottom': 80 +}); + +var v = padding.left; +// 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). + +```javascript +var padding = new Padding({ + 'left': 80, + 'right': 0, + 'top': 80, + 'bottom': 80 +}); + +var v = padding.right; +// returns 0 + +padding.right = 130; + +v = padding.right; +// returns 130 +``` + + + +
+ Padding with right set to 0. +
+
+ + + + + +
+ Padding with right set to 130. +
+
+ + + +* * * + +### Read-Only Properties + + + +#### Padding.prototype.properties + +An array of Padding property names. + +```javascript +var padding = new Padding(); + +var props = padding.properties; +// returns [ 'bottom', 'left', 'right', 'top' ] +``` + +
+ + + +
+ +## Examples + +```javascript +var Padding = require( '@stdlib/plot/vega/padding/ctor' ); + +var padding = new Padding(); +console.log( padding.toJSON() ); +``` + +
+ + + +
+ +
+ + + +
+ +## See Also + +- [`@stdlib/plot/vega/builder`][@stdlib/plot/vega/builder]: Vega visualization builder. + +
+ + + +
+ +[@stdlib/plot/vega/builder]: https://github.com/stdlib-js/stdlib/tree/refactor/plot/lib/node_modules/%40stdlib/plot/vega/builder + +[@stdlib/plot/vega/padding]: https://github.com/stdlib-js/stdlib/tree/refactor/plot/lib/node_modules/%40stdlib/plot/vega/padding/ctor + + + + + +
+ + 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 b/lib/node_modules/@stdlib/plot/vega/padding/ctor/srv/scripts/fig_padding new file mode 100644 index 000000000000..857bf5043ce2 --- /dev/null +++ b/lib/node_modules/@stdlib/plot/vega/padding/ctor/srv/scripts/fig_padding @@ -0,0 +1,508 @@ +#!/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 */ + +// MODULES // + +var resolve = require( 'path' ).resolve; +var join = require( 'path' ).join; +var logger = require( 'debug' ); +var readdir = require( '@stdlib/fs/read-dir' ); +var unlink = require( '@stdlib/fs/unlink' ); +var exists = require( '@stdlib/fs/exists' ); +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 list of directory entries. +* +* @private +* @param {Array} files - directory entries +* @param {Callback} clbk - callback to invoke upon completion +* @returns {void} +*/ +function removeStaleFiles( files, clbk ) { + var idx = 0; + + next(); + + /** + * Processes the next file in the queue. + * + * @private + * @returns {void} + */ + function next() { + var valid; + var file; + var j; + + while ( idx < files.length ) { + file = files[ idx ]; + if ( file.indexOf( '.svg' ) === -1 ) { + idx += 1; + continue; + } + valid = false; + for ( j = 0; j < FIGURES.length; j++ ) { + if ( file === FIGURES[ j ].name + '.svg' ) { + valid = true; + break; + } + } + if ( !valid ) { + debug( 'Removing stale SVG: %s', file ); + unlink( join( IMG_DIR, file ), onRemove ); + return; + } + idx += 1; + } + return clbk( null ); + } + + /** + * Callback invoked upon removing a file. + * + * @private + * @param {(Error|null)} error - error object + * @returns {void} + */ + function onRemove( error ) { + if ( error ) { + return clbk( error ); + } + idx += 1; + next(); + } +} + + +// MAIN // + +/** +* Generates all padding documentation figures. +* +* @private +* @returns {void} +*/ +function main() { + exists( IMG_DIR, onExists ); + + /** + * Callback invoked upon checking directory existence. + * + * @private + * @param {boolean} bool - boolean indicating whether the path exists + * @returns {void} + */ + function onExists( bool ) { + if ( !bool ) { + return generateAll( FIGURES, onComplete ); + } + readdir( IMG_DIR, onRead ); + } + + /** + * Callback invoked upon reading directory contents. + * + * @private + * @param {(Error|null)} error - error object + * @param {Array} files - directory entries + * @returns {void} + */ + function onRead( error, files ) { + if ( error ) { + return onComplete( error ); + } + removeStaleFiles( files, onClean ); + } + + /** + * Callback invoked upon completing stale file cleanup. + * + * @private + * @param {(Error|null)} error - error object + * @returns {void} + */ + function onClean( error ) { + if ( error ) { + return onComplete( error ); + } + 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();