From da97fd55b4d0c9ca903bdebef548b9f44f325733 Mon Sep 17 00:00:00 2001 From: Sachinn-64 Date: Fri, 30 Oct 2026 00:13:05 +0530 Subject: [PATCH] docs: add docs and benchmarks to plot/vega/autosize/ctor --- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown_pkg_readmes status: passed - task: lint_markdown_docs status: na - task: lint_markdown status: na - task: lint_package_json status: na - task: lint_repl_help status: passed - task: lint_javascript_src status: na - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: passed - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: passed - task: lint_typescript_tests status: passed - task: lint_license_headers status: passed --- --- .../@stdlib/plot/vega/autosize/ctor/README.md | 247 ++++++++++++++++++ .../vega/autosize/ctor/benchmark/benchmark.js | 208 +++++++++++++++ .../plot/vega/autosize/ctor/docs/repl.txt | 64 +++++ .../vega/autosize/ctor/docs/types/index.d.ts | 217 +++++++++++++++ .../vega/autosize/ctor/docs/types/test.ts | 141 ++++++++++ 5 files changed, 877 insertions(+) create mode 100644 lib/node_modules/@stdlib/plot/vega/autosize/ctor/README.md create mode 100644 lib/node_modules/@stdlib/plot/vega/autosize/ctor/benchmark/benchmark.js create mode 100644 lib/node_modules/@stdlib/plot/vega/autosize/ctor/docs/repl.txt create mode 100644 lib/node_modules/@stdlib/plot/vega/autosize/ctor/docs/types/index.d.ts create mode 100644 lib/node_modules/@stdlib/plot/vega/autosize/ctor/docs/types/test.ts diff --git a/lib/node_modules/@stdlib/plot/vega/autosize/ctor/README.md b/lib/node_modules/@stdlib/plot/vega/autosize/ctor/README.md new file mode 100644 index 000000000000..4ad18ecb1ea1 --- /dev/null +++ b/lib/node_modules/@stdlib/plot/vega/autosize/ctor/README.md @@ -0,0 +1,247 @@ + + +# Autosize + +> Autosize constructor. + + + +
+ +
+ + + + + +
+ +## Usage + +```javascript +var Autosize = require( '@stdlib/plot/vega/autosize/ctor' ); +``` + +#### Autosize( \[options] ) + +Returns an autosize instance. + +```javascript +var autosize = new Autosize(); +// returns +``` + +The constructor accepts the following `options`: + +- **contains**: method for determining how a size calculation should be performed. Default: `'content'`. +- **resize**: boolean indicating whether to re-calculate an autosize layout on every view update. Default: `false`. +- **type**: autosize method. Default: `'pad'`. + +```javascript +var autosize = new Autosize({ + 'contains': 'padding', + 'resize': true, + 'type': 'fit' +}); +// returns + +var v = autosize.type; +// returns 'fit' +``` + +* * * + +### Writable Properties + + + +#### Autosize.prototype.contains + +Method for determining how a size calculation should be performed. Default: `'content'`. + +```javascript +var autosize = new Autosize(); + +// Set: +autosize.contains = 'padding'; + +// Get: +var v = autosize.contains; +// returns 'padding' +``` + + + +#### Autosize.prototype.resize + +Boolean indicating whether to re-calculate an autosize layout on every view update. Default: `false`. + +```javascript +var autosize = new Autosize(); + +// Set: +autosize.resize = true; + +// Get: +var v = autosize.resize; +// returns true +``` + + + +#### Autosize.prototype.type + +Autosize type. Default: `'pad'`. + +```javascript +var autosize = new Autosize(); + +// Set: +autosize.type = 'none'; + +// Get: +var v = autosize.type; +// returns 'none' +``` + +* * * + +### Read-only Properties + + + +#### Autosize.prototype.properties + +List of enumerable properties. + +```javascript +var autosize = new Autosize(); + +var v = autosize.properties; +// returns [ 'contains', 'resize', 'type' ] +``` + +* * * + +### Methods + + + +#### Autosize.prototype.toJSON() + +Serializes an autosize instance to a JSON object. + +```javascript +var autosize = new Autosize({ + 'type': 'fit' +}); + +var v = autosize.toJSON(); +// returns { 'contains': 'content', 'resize': false, 'type': 'fit' } +``` + +This method is implicitly invoked by `JSON.stringify`. + +```javascript +var autosize = new Autosize({ + 'type': 'fit' +}); + +var str = JSON.stringify( autosize ); +// returns '{"contains":"content","resize":false,"type":"fit"}' +``` + +* * * + +### Events + +#### 'change' + +Emitted whenever a property value changes. + +```javascript +var autosize = new Autosize(); + +autosize.on( 'change', onChange ); + +autosize.type = 'fit'; + +function onChange( event ) { + console.log( 'Updated property: %s', event.property ); +} +``` + +
+ + + + + +
+ +
+ + + + + +
+ +* * * + +## Examples + + + +```javascript +var Autosize = require( '@stdlib/plot/vega/autosize/ctor' ); + +var autosize = new Autosize(); +console.log( autosize.toJSON() ); +``` + +
+ + + + + +
+ +
+ + + + + +
+ +
+ + + + + +
+ +
+ + diff --git a/lib/node_modules/@stdlib/plot/vega/autosize/ctor/benchmark/benchmark.js b/lib/node_modules/@stdlib/plot/vega/autosize/ctor/benchmark/benchmark.js new file mode 100644 index 000000000000..1b69f0cc2682 --- /dev/null +++ b/lib/node_modules/@stdlib/plot/vega/autosize/ctor/benchmark/benchmark.js @@ -0,0 +1,208 @@ +/** +* @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'; + +// MODULES // + +var bench = require( '@stdlib/bench' ); +var instanceOf = require( '@stdlib/assert/instance-of' ); +var isBoolean = require( '@stdlib/assert/is-boolean' ).isPrimitive; +var isString = require( '@stdlib/assert/is-string' ).isPrimitive; +var isPlainObject = require( '@stdlib/assert/is-plain-object' ); +var format = require( '@stdlib/string/format' ); +var pkg = require( './../package.json' ).name; +var Autosize = require( './../lib' ); + + +// MAIN // + +bench( format( '%s::instantiation', pkg ), function benchmark( b ) { + var v; + var i; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = new Autosize(); + if ( !instanceOf( v, Autosize ) ) { + b.fail( 'should return an instance' ); + } + } + b.toc(); + if ( !instanceOf( v, Autosize ) ) { + b.fail( 'should return an instance' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s::instantiation,no_new', pkg ), function benchmark( b ) { + var ctor; + var v; + var i; + + ctor = Autosize; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = ctor(); + if ( !instanceOf( v, Autosize ) ) { + b.fail( 'should return an instance' ); + } + } + b.toc(); + if ( !instanceOf( v, Autosize ) ) { + b.fail( 'should return an instance' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s::instantiation,options', pkg ), function benchmark( b ) { + var opts; + var v; + var i; + + opts = { + 'contains': 'padding', + 'resize': true, + 'type': 'fit' + }; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = new Autosize( opts ); + if ( !instanceOf( v, Autosize ) ) { + b.fail( 'should return an instance' ); + } + } + b.toc(); + if ( !instanceOf( v, Autosize ) ) { + b.fail( 'should return an instance' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s::set,get:contains', pkg ), function benchmark( b ) { + var values; + var v; + var i; + + values = [ + 'content', + 'padding' + ]; + v = new Autosize(); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v.contains = values[ i % values.length ]; + if ( !isString( v.contains ) ) { + b.fail( 'should return a string' ); + } + } + b.toc(); + if ( !isString( v.contains ) ) { + b.fail( 'should return a string' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s::set,get:resize', pkg ), function benchmark( b ) { + var values; + var v; + var i; + + values = [ + true, + false + ]; + v = new Autosize(); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v.resize = values[ i % values.length ]; + if ( !isBoolean( v.resize ) ) { + b.fail( 'should return a boolean' ); + } + } + b.toc(); + if ( !isBoolean( v.resize ) ) { + b.fail( 'should return a boolean' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s::set,get:type', pkg ), function benchmark( b ) { + var values; + var v; + var i; + + values = [ + 'pad', + 'fit', + 'none' + ]; + v = new Autosize(); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v.type = values[ i % values.length ]; + if ( !isString( v.type ) ) { + b.fail( 'should return a string' ); + } + } + b.toc(); + if ( !isString( v.type ) ) { + b.fail( 'should return a string' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); + +bench( format( '%s:toJSON', pkg ), function benchmark( b ) { + var values; + var v; + var o; + var i; + + values = [ + 'pad', + 'fit', + 'none' + ]; + v = new Autosize(); + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v.type = values[ i % values.length ]; + o = v.toJSON(); + if ( typeof o !== 'object' ) { + b.fail( 'should return an object' ); + } + } + b.toc(); + if ( !isPlainObject( o ) ) { + b.fail( 'should return an object' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/lib/node_modules/@stdlib/plot/vega/autosize/ctor/docs/repl.txt b/lib/node_modules/@stdlib/plot/vega/autosize/ctor/docs/repl.txt new file mode 100644 index 000000000000..d5e0663cf23d --- /dev/null +++ b/lib/node_modules/@stdlib/plot/vega/autosize/ctor/docs/repl.txt @@ -0,0 +1,64 @@ + +{{alias}}( [options] ) + Returns an autosize instance. + + Parameters + ---------- + options: Object (optional) + Options. + + options.contains: string (optional) + Method for determining how a size calculation should be performed. + Default: 'content'. + + options.resize: boolean (optional) + Boolean indicating whether to re-calculate an autosize layout on every + view update. Default: false. + + options.type: string (optional) + Autosize method. Default: 'pad'. + + Returns + ------- + autosize: Autosize + Autosize instance. + + autosize.contains + Method for determining how a size calculation should be performed. + + autosize.properties + List of enumerable properties. + + autosize.resize + Boolean indicating whether to re-calculate an autosize layout on every + view update. + + autosize.type + Autosize type. + + autosize.toJSON() + Serializes an autosize instance to a JSON object. + + Examples + -------- + > var autosize = new {{alias}}() + + + // Provide options at instantiation: + > autosize = new {{alias}}( { 'type': 'fit', 'resize': true } ) + + > autosize.type + 'fit' + + // Set a property: + > autosize.contains = 'padding'; + > autosize.contains + 'padding' + + // Serialize to JSON: + > autosize.toJSON() + { 'contains': 'padding', 'resize': true, 'type': 'fit' } + + See Also + -------- + diff --git a/lib/node_modules/@stdlib/plot/vega/autosize/ctor/docs/types/index.d.ts b/lib/node_modules/@stdlib/plot/vega/autosize/ctor/docs/types/index.d.ts new file mode 100644 index 000000000000..e8ecc64d0a1c --- /dev/null +++ b/lib/node_modules/@stdlib/plot/vega/autosize/ctor/docs/types/index.d.ts @@ -0,0 +1,217 @@ +/* +* @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. +*/ + +// TypeScript Version: 4.1 + +/** +* Method for determining how a size calculation should be performed. +*/ +type ContainsMethod = 'content' | 'padding'; + +/** +* Autosize method. +*/ +type AutosizeMethod = 'pad' | 'fit' | 'fit-x' | 'fit-y' | 'none'; + +/** +* Interface describing constructor options. +*/ +interface Options { + /** + * Method for determining how a size calculation should be performed. Default: 'content'. + */ + contains?: ContainsMethod; + + /** + * Boolean indicating whether to re-calculate an autosize layout on every view update. Default: false. + */ + resize?: boolean; + + /** + * Autosize method. Default: 'pad'. + */ + type?: AutosizeMethod; +} + +/** +* Interface describing a JSON-serialized autosize instance. +*/ +interface JSON { + /** + * Method for determining how a size calculation should be performed. + */ + contains: ContainsMethod; + + /** + * Boolean indicating whether to re-calculate an autosize layout on every view update. + */ + resize: boolean; + + /** + * Autosize type. + */ + type: AutosizeMethod; +} + +/** +* Interface describing an autosize instance. +*/ +interface Autosize { + /** + * Method for determining how a size calculation should be performed. + * + * @example + * var autosize = new Autosize(); + * + * autosize.contains = 'padding'; + * + * var v = autosize.contains; + * // returns 'padding' + */ + contains: ContainsMethod; + + /** + * List of enumerable properties. + * + * @example + * var autosize = new Autosize(); + * + * var v = autosize.properties; + * // returns [ 'contains', 'resize', 'type' ] + */ + readonly properties: Array; + + /** + * Boolean indicating whether to re-calculate an autosize layout on every view update. + * + * @example + * var autosize = new Autosize(); + * + * autosize.resize = true; + * + * var v = autosize.resize; + * // returns true + */ + resize: boolean; + + /** + * Autosize type. + * + * @example + * var autosize = new Autosize(); + * + * autosize.type = 'none'; + * + * var v = autosize.type; + * // returns 'none' + */ + type: AutosizeMethod; + + /** + * Serializes an autosize instance to a JSON object. + * + * ## Notes + * + * - This method is implicitly invoked by `JSON.stringify`. + * + * @returns JSON object + * + * @example + * var autosize = new Autosize({ + * 'type': 'fit' + * }); + * + * var v = autosize.toJSON(); + * // returns { 'contains': 'content', 'resize': false, 'type': 'fit' } + */ + toJSON(): JSON; +} + +/** +* Interface defining an autosize constructor which is both "newable" and "callable". +*/ +interface Constructor { + /** + * Autosize constructor. + * + * @param options - constructor options + * @param options.contains - method for determining how a size calculation should be performed (default: 'content') + * @param options.resize - boolean indicating whether to re-calculate an autosize layout on every view update (default: false) + * @param options.type - autosize method (default: 'pad') + * @throws options argument must be an object + * @throws must provide valid options + * @returns autosize instance + * + * @example + * var autosize = new Autosize({ + * 'type': 'fit' + * }); + * + * var v = autosize.type; + * // returns 'fit' + */ + new ( options?: Options ): Autosize; + + /** + * Autosize constructor. + * + * @param options - constructor options + * @param options.contains - method for determining how a size calculation should be performed (default: 'content') + * @param options.resize - boolean indicating whether to re-calculate an autosize layout on every view update (default: false) + * @param options.type - autosize method (default: 'pad') + * @throws options argument must be an object + * @throws must provide valid options + * @returns autosize instance + * + * @example + * var autosize = Autosize({ + * 'type': 'fit' + * }); + * + * var v = autosize.type; + * // returns 'fit' + */ + ( options?: Options ): Autosize; +} + +/** +* Autosize constructor. +* +* @param options - constructor options +* @param options.contains - method for determining how a size calculation should be performed (default: 'content') +* @param options.resize - boolean indicating whether to re-calculate an autosize layout on every view update (default: false) +* @param options.type - autosize method (default: 'pad') +* @throws options argument must be an object +* @throws must provide valid options +* @returns autosize instance +* +* @example +* var autosize = new Autosize(); +* // returns +* +* var v = autosize.toJSON(); +* // returns { 'contains': 'content', 'resize': false, 'type': 'pad' } +*/ +declare var ctor: Constructor; + + +// EXPORTS // + +export = ctor; + +// eslint-doctest-alias: Autosize diff --git a/lib/node_modules/@stdlib/plot/vega/autosize/ctor/docs/types/test.ts b/lib/node_modules/@stdlib/plot/vega/autosize/ctor/docs/types/test.ts new file mode 100644 index 000000000000..122c7ec02fb1 --- /dev/null +++ b/lib/node_modules/@stdlib/plot/vega/autosize/ctor/docs/types/test.ts @@ -0,0 +1,141 @@ +/* +* @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. +*/ + +import Autosize = require( './index' ); + + +// TESTS // + +// The function returns an autosize instance... +{ + new Autosize(); // $ExpectType Autosize + new Autosize( {} ); // $ExpectType Autosize + new Autosize( { 'type': 'fit' } ); // $ExpectType Autosize + new Autosize( { 'contains': 'padding', 'resize': true, 'type': 'fit' } ); // $ExpectType Autosize + + Autosize(); // $ExpectType Autosize + Autosize( {} ); // $ExpectType Autosize + Autosize( { 'type': 'fit' } ); // $ExpectType Autosize + Autosize( { 'contains': 'padding', 'resize': true, 'type': 'fit' } ); // $ExpectType Autosize +} + +// The compiler throws an error if the function is provided an options argument which is not an object... +{ + new Autosize( '5' ); // $ExpectError + new Autosize( 5 ); // $ExpectError + new Autosize( true ); // $ExpectError + new Autosize( false ); // $ExpectError + new Autosize( null ); // $ExpectError + new Autosize( [] ); // $ExpectError + new Autosize( ( x: number ): number => x ); // $ExpectError + + Autosize( '5' ); // $ExpectError + Autosize( 5 ); // $ExpectError + Autosize( true ); // $ExpectError + Autosize( false ); // $ExpectError + Autosize( null ); // $ExpectError + Autosize( [] ); // $ExpectError + Autosize( ( x: number ): number => x ); // $ExpectError +} + +// The compiler throws an error if the function is provided a `contains` option which is not a supported method... +{ + new Autosize( { 'contains': 'abc' } ); // $ExpectError + new Autosize( { 'contains': 5 } ); // $ExpectError + new Autosize( { 'contains': true } ); // $ExpectError + new Autosize( { 'contains': false } ); // $ExpectError + new Autosize( { 'contains': null } ); // $ExpectError + new Autosize( { 'contains': [] } ); // $ExpectError + new Autosize( { 'contains': {} } ); // $ExpectError + new Autosize( { 'contains': ( x: number ): number => x } ); // $ExpectError +} + +// The compiler throws an error if the function is provided a `resize` option which is not a boolean... +{ + new Autosize( { 'resize': '5' } ); // $ExpectError + new Autosize( { 'resize': 5 } ); // $ExpectError + new Autosize( { 'resize': null } ); // $ExpectError + new Autosize( { 'resize': [] } ); // $ExpectError + new Autosize( { 'resize': {} } ); // $ExpectError + new Autosize( { 'resize': ( x: number ): number => x } ); // $ExpectError +} + +// The compiler throws an error if the function is provided a `type` option which is not a supported method... +{ + new Autosize( { 'type': 'abc' } ); // $ExpectError + new Autosize( { 'type': 5 } ); // $ExpectError + new Autosize( { 'type': true } ); // $ExpectError + new Autosize( { 'type': false } ); // $ExpectError + new Autosize( { 'type': null } ); // $ExpectError + new Autosize( { 'type': [] } ); // $ExpectError + new Autosize( { 'type': {} } ); // $ExpectError + new Autosize( { 'type': ( x: number ): number => x } ); // $ExpectError +} + +// The compiler throws an error if the function is provided more than one argument... +{ + new Autosize( {}, {} ); // $ExpectError + Autosize( {}, {} ); // $ExpectError +} + +// An autosize instance has autosize properties... +{ + const autosize = new Autosize(); + + const contains = autosize.contains; // $ExpectType ContainsMethod + const resize = autosize.resize; // $ExpectType boolean + const type = autosize.type; // $ExpectType AutosizeMethod + + if ( contains === 'padding' || resize || type === 'none' ) { + throw new Error( 'unexpected error' ); + } +} + +// The compiler throws an error if an autosize property is assigned an unsupported value... +{ + const autosize = new Autosize(); + + autosize.contains = 'abc'; // $ExpectError + autosize.resize = '5'; // $ExpectError + autosize.type = 'abc'; // $ExpectError +} + +// An autosize instance has a read-only `properties` property... +{ + const autosize = new Autosize(); + + const props = autosize.properties; // $ExpectType string[] + if ( props.length !== 3 ) { + throw new Error( 'unexpected error' ); + } + autosize.properties = [ 'type' ]; // $ExpectError +} + +// An autosize instance has a `toJSON` method which returns a JSON object... +{ + const autosize = new Autosize(); + + autosize.toJSON(); // $ExpectType JSON +} + +// The compiler throws an error if the `toJSON` method is provided arguments... +{ + const autosize = new Autosize(); + + autosize.toJSON( {} ); // $ExpectError +}