fin-hypergrid - npm Package Compare versions

Comparing version 0.2.6 to 0.2.7

images/images.js

@@ -1,2 +0,2 @@
-module.exports = { // This file generated by gulp-imagine-64 at 8:25:56 AM on 4/11/2016
+module.exports = { // This file generated by gulp-imagine-64 at 11:43:48 PM on 4/18/2016
 	"calendar": {
@@ -3,0 +3,0 @@ type: "image/png",

package.json

 {
   "name": "fin-hypergrid",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "Canvas-based high-performance spreadsheet",
@@ -17,3 +17,3 @@ "main": "src/Hypergrid.js",
     "extend-me": "^2.2.2",
-    "filter-tree": "0.3.21",
+    "filter-tree": "^0.3.22",
     "finbars": "^1.5.1",
@@ -20,0 +20,0 @@ "fincanvas": "^1.2.1",

src/behaviors/Behavior.js

@@ -1619,2 +1619,7 @@ /* eslint-env browser */
 
+    /**
+     * @summary Get a reference to the filter attached to the Hypergrid.
+     * @returns {FilterTree}
+     * @memberOf Behavior.prototype
+     */
     getGlobalFilter: function() {
@@ -1624,2 +1629,7 @@ return this.dataModel.getGlobalFilter();
 
+    /**
+     * @summary Attach/detach a filter to a Hypergrid.
+     * @param {FilterTree} [filter] - The filter object. If undefined, any attached filter is removed, turning filtering OFF.
+     * @memberOf Behavior.prototype
+     */
     setGlobalFilter: function(filter) {
@@ -1629,2 +1639,10 @@ this.dataModel.setGlobalFilter(filter);
 
+    /**
+     * @summary Set the case sensitivity of filter tests against data.
+     * @desc Case sensitivity pertains to string compares only. This includes untyped columns, columns typed as strings, typed columns containing data that cannot be coerced to type or when the filter expression operand cannot be coerced.
+     *
+     * NOTE: This is a shared property and affects all grid managed by this instance of the app.
+     * @param {boolean} isSensitive
+     * @memberOf Behavior.prototype
+     */
     setGlobalFilterCaseSensitivity: function(isSensitive) {
@@ -1634,2 +1652,9 @@ this.dataModel.setGlobalFilterCaseSensitivity(isSensitive);
 
+    /**
+     * @param {number|string} columnIndexOrName - The _column filter_ to set.
+     * @param {FilterTreeGetStateOptionsObject} [options] - Passed to the filter's {@link DefaultFilter#getState|getState} method.
+     * @param {boolean} [options.syntax='CQL'] - The syntax to use to describe the filter state. Note that `getFilter`'s default syntax, `'CQL'`, differs from the other get state methods.
+     * @returns {FilterTreeStateObject}
+     * @memberOf Behavior.prototype
+     */
     getFilter: function(columnIndexOrName, options) {
@@ -1639,2 +1664,14 @@ return this.dataModel.getFilter(columnIndexOrName, options);
 
+    /**
+     * @summary Set a particular column filter's state.
+     * @desc After setting the new filter state, reapplies the filter to the data source.
+     * @param {number|string} columnIndexOrName - The _column filter_ to set.
+     * @param {string|object} [state] - A filter tree object or a JSON, SQL, or CQL subexpression string that describes the a new state for the named column filter. The existing column filter subexpression is replaced with a new node based on this state. If it does not exist, the new subexpression is added to the column filters subtree (`filter.columnFilters`).
+     *
+     * If undefined, removes the entire column filter subexpression from the column filters subtree.
+     * @param {FilterTreeSetStateOptionsObject} [options] - Passed to the filter's [setState]{@link http://joneit.github.io/filter-tree/FilterTree.html#setState} method. You may mix in members of the {@link http://joneit.github.io/filter-tree/global.html#FilterTreeValidationOptionsObject|FilterTreeValidationOptionsObject}
+     * @param {string} [options.syntax='CQL'] - The syntax to use to describe the filter state. Note that `setFilter`'s default syntax, `'CQL'`, differs from the other get state methods.
+     * @returns {undefined|Error|string} `undefined` indicates success.
+     * @memberOf Behavior.prototype
+     */
     setFilter: function(columnIndexOrName, state, options) {
@@ -1644,2 +1681,26 @@ this.dataModel.setFilter(columnIndexOrName, state, options);
 
+    /**
+     * @param {FilterTreeGetStateOptionsObject} [options] - Passed to the filter's {@link DefaultFilter#getState|getState} method.
+     * @returns {FilterTreeStateObject}
+     * @memberOf Behavior.prototype
+     */
+    getFilters: function(options) {
+        return this.dataModel.getFilters(options);
+    },
+
+    /**
+     * @param {FilterTreeStateObject} state
+     * @param {FilterTreeSetStateOptionsObject} [options] - Passed to the filter's [setState]{@link http://joneit.github.io/filter-tree/FilterTree.html#setState} method. You may mix in members of the {@link http://joneit.github.io/filter-tree/global.html#FilterTreeValidationOptionsObject|FilterTreeValidationOptionsObject}
+     * @returns {undefined|Error|string} `undefined` indicates success.
+     * @memberOf Behavior.prototype
+     */
+    setFilters: function(state, options) {
+        this.dataModel.setFilters(state, options);
+    },
+
+    /**
+     * @param {FilterTreeGetStateOptionsObject} [options] - Passed to the filter's {@link DefaultFilter#getState|getState} method.
+     * @returns {FilterTreeStateObject}
+     * @memberOf Behavior.prototype
+     */
     getTableFilter: function(options) {
@@ -1649,2 +1710,8 @@ return this.dataModel.getTableFilter(options);
 
+    /**
+     * @param {FilterTreeStateObject} state
+     * @param {FilterTreeSetStateOptionsObject} [options] - Passed to the filter's [setState]{@link http://joneit.github.io/filter-tree/FilterTree.html#setState} method. You may mix in members of the {@link http://joneit.github.io/filter-tree/global.html#FilterTreeValidationOptionsObject|FilterTreeValidationOptionsObject}
+     * @returns {undefined|Error|string} `undefined` indicates success.
+     * @memberOf Behavior.prototype
+     */
     setTableFilter: function(state, options) {
@@ -1651,0 +1718,0 @@ this.dataModel.setTableFilter(state, options);

src/dataModels/JSON.js

@@ -623,2 +623,7 @@ 'use strict';
 
+    /**
+     * @summary Get a reference to the filter attached to the Hypergrid.
+     * @returns {FilterTree}
+     * @memberOf dataModels.JSON.prototype
+     */
     getGlobalFilter: function() {
@@ -629,4 +634,5 @@ return this.getGlobalFilterDataSource().get();
     /**
+     * @summary Attach/detach a filter to a Hypergrid.
+     * @param {FilterTree} [filter] - The filter object. If undefined, any attached filter is removed, turning filtering OFF.
      * @memberOf dataModels.JSON.prototype
-     * @param {FilterTree} [filter] - If undefined, removes (deletes) the filter (i.e., turns filtering OFF).
      */
@@ -638,2 +644,10 @@ setGlobalFilter: function(filter) {
 
+    /**
+     * @summary Set the case sensitivity of filter tests against data.
+     * @desc Case sensitivity pertains to string compares only. This includes untyped columns, columns typed as strings, typed columns containing data that cannot be coerced to type or when the filter expression operand cannot be coerced.
+     *
+     * NOTE: This is a shared property and affects all grid managed by this instance of the app.
+     * @param {boolean} isSensitive
+     * @memberOf dataModels.JSON.prototype
+     */
     setGlobalFilterCaseSensitivity: function(isSensitive) {
@@ -645,5 +659,8 @@ this.getGlobalFilter().setCaseSensitivity(isSensitive);
     /**
-     * @summary Get a particular column filter state.
-     * @param {number|string} columnIndexOrName - The _column filter_ to set.
-     * @param {string} [options.syntax='CQL'] - For other possible values, see {@link http://joneit.github.io/filter-tree/global.html#filterTreeSetStateOptionsObject|filterTreeSetStateOptionsObject}.
+     * @summary Get a particular column filter's state.
+     * @param {string} columnName
+     * @param {FilterTreeGetStateOptionsObject} [options] - Passed to the filter's {@link DefaultFilter#getState|getState} method.
+     * @param {boolean} [options.syntax='CQL'] - The syntax to use to describe the filter state. Note that `getFilter`'s default syntax, `'CQL'`, differs from the other get state methods.
+     * @returns {FilterTreeStateObject}
+     * @memberOf dataModels.JSON.prototype
      */
@@ -658,10 +675,12 @@ getFilter: function(columnIndexOrName, options) {
     /**
-     * @summary Set a particular column filter state.
+     * @summary Set a particular column filter's state.
      * @desc After setting the new filter state, reapplies the filter to the data source.
      * @param {number|string} columnIndexOrName - The _column filter_ to set.
-     * @param {string|object} [state] - If undefined, removes column filter from the filter tree.
+     * @param {string|object} [state] - A filter tree object or a JSON, SQL, or CQL subexpression string that describes the a new state for the named column filter. The existing column filter subexpression is replaced with a new node based on this state. If it does not exist, the new subexpression is added to the column filters subtree (`filter.columnFilters`).
      *
-     * Otherwise, column filter is replaced (if it already exists) or added (if new).
-     * @param {filterTreeSetStateOptionsObject} [options]
-     * @param {string} [options.syntax='CQL'] - For other possible values, see {@link http://joneit.github.io/filter-tree/global.html#filterTreeSetStateOptionsObject|filterTreeSetStateOptionsObject}.
+     * If undefined, removes the entire column filter subexpression from the column filters subtree.
+     * @param {FilterTreeSetStateOptionsObject} [options] - Passed to the filter's [setState]{@link http://joneit.github.io/filter-tree/FilterTree.html#setState} method. You may mix in members of the {@link http://joneit.github.io/filter-tree/global.html#FilterTreeValidationOptionsObject|FilterTreeValidationOptionsObject}
+     * @param {string} [options.syntax='CQL'] - The syntax to use to describe the filter state. Note that `setFilter`'s default syntax, `'CQL'`, differs from the other get state methods.
+     * @returns {undefined|Error|string} `undefined` indicates success.
+     * @memberOf dataModels.JSON.prototype
      */
@@ -677,6 +696,26 @@ setFilter: function(columnIndexOrName, state, options) {
     /**
-     *
-     * @param options
-     * @returns {*|FilterTreeStateObject}
+     * @param {FilterTreeGetStateOptionsObject} [options] - Passed to the filter's {@link DefaultFilter#getState|getState} method.
+     * @returns {FilterTreeStateObject}
+     * @memberOf dataModels.JSON.prototype
      */
+    getFilters: function(options) {
+        return this.getGlobalFilter().getColumnFiltersState(options);
+    },
+
+    /**
+     * @param {FilterTreeStateObject} state
+     * @param {FilterTreeSetStateOptionsObject} [options] - Passed to the filter's [setState]{@link http://joneit.github.io/filter-tree/FilterTree.html#setState} method. You may mix in members of the {@link http://joneit.github.io/filter-tree/global.html#FilterTreeValidationOptionsObject|FilterTreeValidationOptionsObject}
+     * @returns {undefined|Error|string} `undefined` indicates success.
+     * @memberOf dataModels.JSON.prototype
+     */
+    setFilters: function(state, options) {
+        this.getGlobalFilter().setColumnFiltersState(state, options);
+        this.applyAnalytics();
+    },
+
+    /**
+     * @param {FilterTreeGetStateOptionsObject} [options] - Passed to the filter's {@link DefaultFilter#getState|getState} method.
+     * @returns {FilterTreeStateObject}
+     * @memberOf dataModels.JSON.prototype
+     */
     getTableFilter: function(options) {
@@ -688,5 +727,6 @@ return this.getGlobalFilter().getTableFilterState(options);
      * @summary Set a the table filter state.
-     * @param {string} state
-     * @param {filterTreeSetStateOptionsObject} [options]
-     * @param {string} [options.syntax='CQL']
+     * @param {FilterTreeStateObject} state
+     * @param {FilterTreeSetStateOptionsObject} [options] - Passed to the filter's [setState]{@link http://joneit.github.io/filter-tree/FilterTree.html#setState} method. You may mix in members of the {@link http://joneit.github.io/filter-tree/global.html#FilterTreeValidationOptionsObject|FilterTreeValidationOptionsObject}
+     * @returns {undefined|Error|string} `undefined` indicates success.
+     * @memberOf dataModels.JSON.prototype
      */
@@ -693,0 +733,0 @@ setTableFilter: function(state, options) {

src/filter/DefaultFilter.js

@@ -128,5 +128,9 @@ 'use strict';
  *
- * @param {FilterTreeOptionsObject} options - You must provide column schema, either for the whole filter tree through `options.schema` or `options.state.schema` or for the specific nodes that need to render column list drop-downs.
+ * See also {@tutorial filter-api}.
  *
- * > NOTE: If `options.state` is undefined, it is defined here as a new {@link makeNewRoot|empty state scaffold) to hold new table filter and column filter expressions to be added through UI.
+ * @param {FilterTreeOptionsObject} options - You hsould provide a column schema. The easiest approach is to provide a schema for the entire filter tree through `options.schema`.
+ *
+ * Although not recommended, the column schema can also be embedded in the state object, either at the root, `options.state.schema`, or for any descendant node. For example, a separate schema could be provided for each expression or subexpression that need to render column list drop-downs.
+ *
+ * NOTE: If `options.state` is undefined, it is defined in `preInitialize()` as a new empty state scaffold (see {@link makeNewRoot}) with the two trunks to hold a table filter and column filters. Expressions and subexpressions can be added to this empty scaffold either programmatically or through the Query Builder UI.
  */
@@ -166,2 +170,6 @@
         }
+
+        if (this.type === 'columnFilter') {
+            this.dontPersist.schema = true;
+        }
     },
@@ -181,13 +189,18 @@
      * @summary Make a new empty Hypergrid filter tree state object.
-     * @desc This function makes a new default state object as used by Hypergrid, a root with exactly two persisted child nodes:
+     * @desc This function makes a new default state object as used by Hypergrid, a root with exactly two "trunks."
      *
-     * * children[0] represents the _table filter,_ a series of any number of filter expressions and/or subexpressions
-     * * children[1] represents the _column filters,_ a series of subexpressions, one per active column filter
+     * > **Definition:** A *trunk* is defined as a child node with a truthy `keep` property, making this node immune to the usual pruning that would occur when it has no child nodes of its own. To be a true trunk, all ancestor nodes to be trunks as well. Note that the root is a natural trunk; it does not require a `keep` property.
      *
+     * The two trunks of the Hypergrid filter are:
+     * * The **Table Filter** (left trunk, or `children[0]`), a hierarchy of filter expressions and subexpressions.
+     * * The **Column Filters** (right trunk, or `children[1]`), a series of subexpressions, one per active column filter. Each subexpression contains any number of expressions bound to that column but no further subexpressions.
+     *
      * The `operator` properties for all subexpressions default to `'op-and'`, which means:
-     * * AND all table filter expressions and subexpressions together (may be changed from UI)
-     * * AND all column Filters subexpressions together (cannot be changed from UI)
-     * * AND table filters and column filters together (cannot be changed from UI)
+     * * All table filter expressions and subexpressions are AND'd together. (This is just the default and may be changed from the UI.)
+     * * All expressions within a column filter subexpression are AND'd together. (This is just the default and may be changed from the UI.)
+     * * All column Filters subexpressions are AND'd together. (This may not be changed from UI.)
+     * * Finally, the table filter and column filters are AND'd together. (This may not be changed from UI.)
      *
-     * @returns a new instance of a Hyperfilter root
+     * @returns {object} A plain object to serve as a filter-tree state object representing a new Hypergrid filter.
+     *
      * @memberOf DefaultFilter.prototype
@@ -224,4 +237,6 @@ */
      * @summary Get the column filter subexpression node.
-     * @desc The column filter subexpression nodes are child nodes of the `columnFitlers` branch of the Hypergrid filter tree.
-     * Each such node contains all the column filter expressions for the named column. It will never be empty; rather if there is no column filter for the named column, it won't exist in `columnFilters`.
+     * @desc Each column filter subexpression node is a child node of the `columnFilters` trunk of the Hypergrid filter tree.
+     * Each such node contains all the column filter expressions for the named column. It will never be empty; if there is no column filter for the named column, it won't exist in `columnFilters`.
+     *
+     * CAUTION: This is the actual node object. Do not confuse it with the column filter _state_ object (for which see the {@link DefaultFilter#getColumnFilterState|getColumnFilterState()} method).
      * @param {string} columnName
@@ -236,17 +251,15 @@ * @returns {undefined|DefaultFilter} Returns `undefined` if the column filter does not exist.
 
-    /** @typedef {object} filterTreeGetStateOptionsObject
-     * See filter-tree's {@link http://joneit.github.io/filter-tree/FilterTree.html#getState|getState} options object.
+    /** @typedef {object} FilterTreeGetStateOptionsObject
+     * See the {@link http://joneit.github.io/filter-tree/global.html#FilterTreeGetStateOptionsObject|type definition} in the filter-tree documentation.
      */
 
-    /** @typedef {object} filterTreeSetStateOptionsObject
-     * See filter-tree's {@link http://joneit.github.io/filter-tree/FilterNode.html#setState|setState} options object.
+    /** @typedef {object} FilterTreeSetStateOptionsObject
+     * See the {@link http://joneit.github.io/filter-tree/global.html#FilterTreeSetStateOptionsObject|type definition} in the filter-tree documentation.
      */
 
     /**
-     *
-     * @param columnName
-     * @param {FilterTreeGetStateOptionsObject} [options] - Passed to `getState`.
-     * @param {boolean} [options.syntax='CQL'] - The syntax to use to describe the filter state.
-     *
-     * NOTE: Not all available syntaxes include the meta-data.
+     * @summary Get a particular column filter's state.
+     * @param {FilterTreeGetStateOptionsObject} [options] - Passed to the filter's {@link DefaultFilter#getState|getState} method.
+     * @param {boolean} [options.syntax='CQL'] - The syntax to use to describe the filter state. Note that `getFilter`'s default syntax, `'CQL'`, differs from the other get state methods.
+     * @returns {FilterTreeStateObject}
      * @memberOf DefaultFilter.prototype
@@ -272,10 +285,15 @@ */
     /**
+     * @summary Set a particular column filter's state.
+     * @desc Adds CQL support to this.getState().
      *
-     * @param columnName
-     * @param {string|object} [state] - If undefined, removes column filter from the filter tree.
+     * @param {string} columnName
      *
-     * Otherwise, column filter is replaced (if it already exists) or added (if new).
-     * @param {filterTreeSetStateOptionsObject} [options]
-     * @param {boolean} [options.syntax='CQL'] For other possible values, see {@link http://joneit.github.io/filter-tree/global.html#filterTreeSetStateOptionsObject|filterTreeSetStateOptionsObject}.
+     * @param {string|object} [state] - A filter tree object or a JSON, SQL, or CQL subexpression string that describes the a new state for the named column filter. The existing column filter subexpression is replaced with a new node based on this state. If it does not exist, the new subexpression is added to the column filters subtree (`this.root.columnFilters`).
      *
+     * If undefined, removes the entire column filter subexpression from the column filters subtree.
+     *
+     * @param {FilterTreeSetStateOptionsObject} [options] - Passed to the filter's [setState]{@link http://joneit.github.io/filter-tree/FilterTree.html#setState} method. You may mix in members of the {@link http://joneit.github.io/filter-tree/global.html#FilterTreeValidationOptionsObject|FilterTreeValidationOptionsObject}
+     *
+     * @param {boolean} [options.syntax='CQL'] - The syntax to use to describe the filter state. Note that `setColumnFilterState`'s default syntax, `'CQL'`, differs from the other get state methods.
+     *
      * @returns {undefined|Error|string} `undefined` indicates success.
@@ -323,3 +341,3 @@
 
-        if (error && subexpression) {
+        if (subexpression && (!state || error)) {
             // remove subexpression representing this column
@@ -333,5 +351,19 @@ subexpression.remove();
     /**
+     * @summary Get state of all column filters.
+     * @param {FilterTreeGetStateOptionsObject} [options] - Passed to the filter's {@link DefaultFilter#getState|getState} method.
+     * @returns {FilterTreeStateObject}
+     * @memberOf DefaultFilter.prototype
+     */
+    getColumnFiltersState: function(options) {
+        if (options && options.syntax === 'CQL') {
+            throw 'The CQL syntax is intended for use on a single column filter only. It does not support multiple columns or subexpressions.';
+        }
+        return this.root.columnFilters.getState(options);
+    },
+
+    /**
+     * @summary Set state of all column filters.
+     * @desc Note that the column filters implementation depends on the nodes having certain meta-data; you should not be calling this without these meta-data being in place. Specifically `type = 'columnFilters'` and  `keep = true` for the column filters subtree and`type = 'columnFilter'` for each individual column filter subexpression. In addition the subtree operators should always be `'op-and'`.
      * @param {string} state
-     * @param {filterTreeSetStateOptionsObject} options
-     * @param {boolean} [options.syntax='auto'] For other possible values, see {@link http://joneit.github.io/filter-tree/global.html#filterTreeSetStateOptionsObject|filterTreeSetStateOptionsObject}.
+     * @param {FilterTreeSetStateOptionsObject} [options] - Passed to the filter's [setState]{@link http://joneit.github.io/filter-tree/FilterTree.html#setState} method. You may mix in members of the {@link http://joneit.github.io/filter-tree/global.html#FilterTreeValidationOptionsObject|FilterTreeValidationOptionsObject}
      *
@@ -342,8 +374,8 @@ * @returns {undefined|Error|string} `undefined` indicates success.
      */
-    setTableFilterState: function(state, options) {
+    setColumnFiltersState: function(state, options) {
         var error;
 
         if (state) {
-            this.root.tableFilter.setState(state);
-            error = this.root.tableFilter.invalid(options);
+            this.root.columnFilters.setState(state, options);
+            error = this.root.columnFilters.invalid(options);
         }
@@ -355,18 +387,31 @@
     /**
-     *
-     * @param {string} [options.syntax='object'] - The syntax to use to describe the filter state.
-     *
-     * NOTE: Not all available syntaxes include the meta-data.
-     *
-     * NOTE: The `'CQL'` syntax is intended for column filters only. Do *not* use for table filter state! It does not support subexpressions and will throw an error if it encounters any subexpressions.
-     *
-     * @returns {*|FilterTreeStateObject}
-     *
+     * @param {FilterTreeGetStateOptionsObject} [options] - Passed to the filter's {@link DefaultFilter#getState|getState} method.
+     * @returns {FilterTreeStateObject}
      * @memberOf DefaultFilter.prototype
      */
     getTableFilterState: function(options) {
-        return this.tableFilter.getState(options);
+        if (options && options.syntax === 'CQL') {
+            throw 'The CQL syntax is intended for use on a single column filter only. It does not support multiple columns or subexpressions.';
+        }
+        return this.root.tableFilter.getState(options);
     },
 
     /**
+     * @param {string} state
+     * @param {FilterTreeSetStateOptionsObject} [options] - Passed to the filter's [setState]{@link http://joneit.github.io/filter-tree/FilterTree.html#setState} method. You may mix in members of the {@link http://joneit.github.io/filter-tree/global.html#FilterTreeValidationOptionsObject|FilterTreeValidationOptionsObject}
+     * @returns {undefined|Error|string} `undefined` indicates success.
+     * @memberOf DefaultFilter.prototype
+     */
+    setTableFilterState: function(state, options) {
+        var error;
+
+        if (state) {
+            this.root.tableFilter.setState(state, options);
+            error = this.root.tableFilter.invalid(options);
+        }
+
+        return error;
+    },
+
+    /**
      * @desc The CQL syntax should only be requested for a subtree containing homogeneous column names and no subexpressions.
@@ -376,2 +421,4 @@ *
      *
+     * NOTE: CQL is not intended to be used outside the context of a `columnFilters` subexpression.
+     *
      * @returns {FilterTreeStateObject}
@@ -378,0 +425,0 @@ *

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Native code

Supply chain risk

Contains native code (e.g., compiled binaries or shared libraries). Including native code can obscure malicious behavior.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

696869

increased by0.63%

Lines of code

17164

increased by1.4%

Number of medium supply chain risk alerts

0

decreased by-100%

Dependency changes

• + Addedfilter-tree@0.3.41(transitive)

• - Removedfilter-tree@0.3.21(transitive)

• Updatedfilter-tree@^0.3.22