feat: add plot/vega/compare/ctor

lib/node_modules/@stdlib/plot/vega/compare/ctor/examples/index.js

@@ -0,0 +1,43 @@
+/**
+* @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';
+
+var SignalReference = require( '@stdlib/plot/vega/signal/reference' );
+var Compare = require( './../lib' );
+
+// Single field comparator:
+var compare = new Compare({
+	'field': 'amount',
+	'order': 'ascending'
+});
+console.log( compare.toJSON() );
+
+// Multi-field comparator:
+compare = new Compare({
+	'field': [ 'amount', 'date' ],
+	'order': [ 'descending', 'ascending' ]
+});
+console.log( compare.toJSON() );
+
+// Signal reference comparator:
+compare = new Compare({
+	'field': new SignalReference( 'sortField' ),
+	'order': new SignalReference( 'sortOrder' )
+});
+console.log( compare.toJSON() );

lib/node_modules/@stdlib/plot/vega/compare/ctor/lib/change_event.js

@@ -0,0 +1,41 @@
+/**
+* @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';
+
+// MAIN //
+
+/**
+* Returns a new change event object.
+*
+* @private
+* @param {string} property - property name
+* @returns {Object} event object
+*/
+function event( property ) { // eslint-disable-line stdlib/no-redeclare
+	return {
+		'type': 'update',
+		'source': 'compare',
+		'property': property
+	};
+}
+
+
+// EXPORTS //
+
+module.exports = event;

lib/node_modules/@stdlib/plot/vega/compare/ctor/lib/defaults.js

@@ -0,0 +1,43 @@
+/**
+* @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';
+
+// MAIN //
+
+/**
+* Returns defaults.
+*
+* @private
+* @returns {Object} default options
+*
+* @example
+* var o = defaults();
+* // returns {...}
+*/
+function defaults() {
+	return {
+		// Desired sort order for each field:
+		'order': [ 'ascending' ]
+	};
+}
+
+
+// EXPORTS //
+
+module.exports = defaults;

lib/node_modules/@stdlib/plot/vega/compare/ctor/lib/field/get.js

@@ -0,0 +1,43 @@
+/**
+* @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.
+*/
+
+/* eslint-disable no-invalid-this */
+
+'use strict';
+
+// MODULES //
+
+var prop = require( './properties.js' );
+
+
+// MAIN //
+
+/**
+* Returns the data fields to sort.
+*
+* @private
+* @returns {(Array<string>|SignalReference|void)} data fields
+*/
+function get() {
+	return this[ prop.private ];
+}
+
+
+// EXPORTS //
+
+module.exports = get;

lib/node_modules/@stdlib/plot/vega/compare/ctor/lib/field/properties.js

@@ -0,0 +1,33 @@
+/**
+* @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 property2object = require( '@stdlib/plot/vega/base/property2object' );
+
+
+// MAIN //
+
+var obj = property2object( 'field' );
+
+
+// EXPORTS //
+
+module.exports = obj;

lib/node_modules/@stdlib/plot/vega/compare/ctor/lib/field/set.js

@@ -0,0 +1,104 @@
+/**
+* @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.
+*/
+
+/* eslint-disable no-invalid-this */
+
+'use strict';
+
+// MODULES //
+
+var logger = require( 'debug' );
+var isUndefined = require( '@stdlib/assert/is-undefined' );
+var isString = require( '@stdlib/assert/is-string' ).isPrimitive;
+var isStringArray = require( '@stdlib/assert/is-string-array' ).primitives;
+var isSignalReference = require( '@stdlib/plot/vega/base/assert/is-signal-reference' );
+var hasEqualValues = require( '@stdlib/array/base/assert/has-equal-values' );
+var copy = require( '@stdlib/array/base/copy' );
+var join = require( '@stdlib/array/base/join' );
+var format = require( '@stdlib/string/format' );
+var defaults = require( './../defaults.js' );
+var changeEvent = require( './../change_event.js' );
+var prop = require( './properties.js' );
+
+
+// VARIABLES //
+
+var debug = logger( 'vega:compare:set:'+prop.name );
+
+
+// MAIN //
+
+/**
+* Sets the data fields to sort.
+*
+* @private
+* @param {(string|Array<string>|SignalReference)} value - input value
+* @throws {TypeError} must be a string, an array of strings, or a SignalReference
+* @returns {void}
+*/
+function set( value ) {
+	var nfields;
+	var order;
+	var isStr;
+	var opts;
+	var i;
+
+	if ( isSignalReference( value ) ) {
+		if ( this[ prop.private ] !== value ) {
+			debug( 'Current value: %s. New value: %s.', this[ prop.private ], value );
+			this[ prop.private ] = value;
+			this.emit( 'change', changeEvent( prop.name ) );
+		}
+		return;
+	}
+	isStr = isString( value );
+	if ( !isStr && !isStringArray( value ) ) {
+		throw new TypeError( format( 'invalid assignment. `%s` must be a string, an array of strings, or a signal reference. Value: `%s`.', prop.name, value ) );
+	}
+	if ( isStr ) {
+		value = [ value ];
+	} else {
+		value = copy( value );
+	}
+	if ( !hasEqualValues( value, this[ prop.private ] ) ) {
+		debug( 'Current value: ["%s"]. New value: ["%s"].', join( this[ prop.private ], '", "' ), join( value, '", "' ) );
+		this[ prop.private ] = value;
+		this.emit( 'change', changeEvent( prop.name ) );
+
+		// Adjust the order array to match the new number of fields...
+		nfields = value.length;
+		order = this._order;
+		if ( order ) {
+			if ( order.length < nfields ) {
+				// Pad with default 'ascending' values...
+				opts = defaults();
+				for ( i = order.length; i < nfields; i++ ) {
+					order.push( opts.order[ 0 ] );
+				}
+			} else if ( order.length > nfields ) {
+				// Truncate excess order entries...
+				order.length = nfields;
+			}
+		}
+	}
+}
+
+
+// EXPORTS //
+
+module.exports = set;

lib/node_modules/@stdlib/plot/vega/compare/ctor/lib/index.js

@@ -0,0 +1,42 @@
+/**
+* @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';
+
+/**
+* Compare constructor.
+*
+* @module @stdlib/plot/vega/compare/ctor
+*
+* @example
+* var Compare = require( '@stdlib/plot/vega/compare/ctor' );
+*
+* var compare = new Compare({
+*     'field': 'amount'
+* });
+* // returns <Compare>
+*/
+
+// MODULES //
+
+var main = require( './main.js' );
+
+
+// EXPORTS //
+
+module.exports = main;