Improve validation API

.eslintrc.js

@@ -196,6 +196,7 @@ module.exports = {
             "@typescript-eslint/ban-ts-comment": 0,
             "@typescript-eslint/no-floating-promises": 0,
             "@typescript-eslint/no-non-null-assertion": 0,
+            "@typescript-eslint/no-non-null-asserted-optional-chain": 0,
         }
       },
     ],

.npmrc

@@ -1,3 +1,4 @@
 engine-strict=true
 include-workspace-root=false
 prefer-workspace-packages=true
+auto-install-peers=false

.vscode/launch.json

@@ -2,10 +2,45 @@
   "version": "0.2.0",
   "configurations": [
     {
-      "name": "Run Karma tests with debugger",
-      "type": "node-terminal",
+      "name": "Run examples",
+      "type": "node",
       "request": "launch",
-      "command": "npm run test-debug",
+      "cwd": "${workspaceRoot}/packages/examples",
+      "program": "${workspaceRoot}/packages/examples/node_modules/webpack/bin/webpack.js",
+      "args": [
+        "serve",
+      ],
+      "env": {
+        "NODE_ENV": "development"
+      },
+      "console": "integratedTerminal",
+      "autoAttachChildProcesses": true,
+    },
+    {
+      "name": "Open Chrome with examples",
+      "type": "chrome",
+      "request": "launch",
+      "url": "http://localhost:3001/",
+      "webRoot": "${workspaceFolder}/packages/examples",
+    },
+    {
+      "name": "Run Karma tests in debug mode",
+      "type": "node",
+      "request": "launch",
+      "cwd": "${workspaceRoot}/packages/tests",
+      "program": "${workspaceRoot}/packages/tests/node_modules/karma/bin/karma",
+      "args": [
+        "start",
+        "./karma.conf.js",
+        // "--filter",
+        // "${input:filterTests}",
+      ],
+      "env": {
+        "TEST_WATCH": "1",
+        "TEST_DEBUG": "1",
+      },
+      "console": "integratedTerminal",
+      "internalConsoleOptions": "neverOpen"
     },
     {
       "name": "Attach to Karma",
@@ -17,6 +52,32 @@
       "timeout": 600000,
       "sourceMaps": true,
       "webRoot": "${workspaceFolder}/packages/tests",
+    },
+    {
+      "name": "Run Karma tests in watch mode",
+      "type": "node",
+      "request": "launch",
+      "cwd": "${workspaceRoot}/packages/tests",
+      "program": "${workspaceRoot}/packages/tests/node_modules/karma/bin/karma",
+      "args": [
+        "start",
+        "./karma.conf.js",
+        // "--filter",
+        // "${input:filterTests}",
+      ],
+      "env": {
+        "TEST_WATCH": "1",
+      },
+      "console": "integratedTerminal",
+      "internalConsoleOptions": "neverOpen"
+    },
+  ],
+  "inputs": [
+    {
+      "id": "filterTests",
+      "type": "promptString",
+      "description": "Enter test filenames to filter (without extension), space separated. Or leave empty to test all specs.",
+      "default": ""
     }
   ]
 }

.vscode/settings.json

@@ -1,3 +1,5 @@
 {
-  "typescript.tsdk": "node_modules/typescript/lib"
+  "typescript.tsdk": "node_modules/typescript/lib",
+  "npm.packageManager": "pnpm",
+  "pnpm.runInTerminal": true
 }

CHANGELOG.md

@@ -1,4 +1,20 @@
 # Changelog
+- 6.5.0
+  - Breaking: `Utils.validateTree` returns array of errors (PR #1034)
+  - Breaking: `removeIncompleteRulesOnLoad` by default is false
+  - Added config `removeEmptyRulesOnLoad` (default true) (PR #1034)
+  - Deprecated `Utils.validateAndFixTree` and `Utils.checkTree` (and removed type defs). 
+    Use `Utils.sanitizeTree().fixedTree` instead (PR #1034)
+  - `Utils.validateTree` now checks LHS and RHS are completed (issues #977, #781) (PR #1034)
+  - Fixed import of `select_any_in` operator from JsonLogic (issue #1005) (PR #1034)
+  - Fixed issue #1036 (PR #1034)
+  - Fixed validation of date ranges (issue #374) (PR #1034)
+  - Function `validateValue` in `fieldSettings` config can now return object `{error, fixedValue}`, error can be `{key, args}` for i18n (PR #1034)
+  - Added `optimizeRenderWithInternals` to `settings`, default is `false` (PR #1034)
+  - Updated type `RuleGroupExtProperties` (issue #1021) (PR #1034)
+  - Fixed typedef errors (issue #1016) (PR #1034)
+  - Fixed issue with antd and date/time pickers (issue #1033) (PR #1034)
+  - Added `onInit` prop to `<Query>`. Added 4th argument `actions` to `onInit` and `onChange` (PR #1034)
 - 6.4.3
   - Fixed the issue when using func with arg of type `multiselect` (PR #997)
   - Updated `immutable` from v3 to v4 (PR #997)

CONFIG.adoc

@@ -10,14 +10,15 @@ ifdef::env-github[]
 :warning-caption: :warning:
 endif::[]
 
-:queryString:  https://github.com/ukrbublik/react-awesome-query-builder/#querystring-immutablevalue-config-isfordisplay\--false---string
+:queryString:  https://github.com/ukrbublik/react-awesome-query-builder/#querystring
+:i18n:         https://github.com/ukrbublik/react-awesome-query-builder/#i18n
 :config1:      https://github.com/ukrbublik/react-awesome-query-builder/tree/master/packages/sandbox_simple/src/demo/config.jsx
 :config2:      https://github.com/ukrbublik/react-awesome-query-builder/tree/master/packages/sandbox/src/demo/config.tsx
 :config3:      https://github.com/ukrbublik/react-awesome-query-builder/tree/master/packages/examples/demo/config.tsx
 :funcs:        https://github.com/ukrbublik/react-awesome-query-builder/tree/master/packages/core/modules/config/funcs.js
 :renderSwitch: https://github.com/ukrbublik/react-awesome-query-builder/blob/master/packages/antd/modules/config/index.jsx#L54
 :config_ser:   https://github.com/ukrbublik/react-awesome-query-builder/blob/master/packages/sandbox_next/lib/config_ser.js
-:d_ts:   https://github.com/ukrbublik/react-awesome-query-builder/blob/master/packages/core/modules/index.d.ts
+:d_ts:         https://github.com/ukrbublik/react-awesome-query-builder/blob/master/packages/core/modules/index.d.ts
 
 = Config format
 
@@ -219,8 +220,10 @@ Example:
 |fieldSettings.treeValues |+ for tree (multi)select | |List of values for tree (multi)select widget. +
   Example: `[{value: 'warm', title: 'Warm colors'}, {value: 'red', title: 'Red', parent: 'warm'}, {value: 'orange', title: 'Orange', parent: 'warm'}]` 
    (or alternatively `[{value: 'warm', title: 'Warm colors', children: [ {value: 'red', title: 'Red'}, {value: 'orange', title: 'Orange'} ]}]`)
-|fieldSettings.validateValue | | |Function to validate entered value. Return true/false or error string / null. +
-  `(mixed val, Object fieldSettings) => boolean \| string \| null`
+|fieldSettings.validateValue | | |Function to validate input value. +
+  Simple way: return true/false. Advanced: if value is valid, return `null`, otherwise return error string or object `{error, fixedValue?}`. +
+  `error` can be a string or an object `{key, args}` to use {i18n}[i18n]. +
+  `(val: any, fieldSettings: Object) => boolean \| string \| {error: string | Object, fixedValue?: any} \| null`
 |fieldSettings.allowCustomValues |- for `multiselect` widget |false |If true, user can provide own options in multiselect, otherwise they will be limited to `listValues`
 |fieldSettings.showSearch |- for (multi)select, tree (multi)select|false |Show search (autocomplete)?
 |fieldSettings.treeExpandAll |- for `treeselect/treemultiselect` widgets|false |Whether to expand all nodes by default
@@ -310,7 +313,7 @@ Behaviour settings:
   If you want to enable comparing with result of function, add `func` like in example above.
 |fieldSources |`["field"]` |To enable functions in LHS, set to `["field", "func"]`
 |keepInputOnChangeFieldSrc |true |Keep value entered in RHS after changing source of LHS? 
-|showErrorMessage |false |Show error message in QueryBuilder if validateValue() in field config returns false
+|showErrorMessage |false |Show error message in QueryBuilder if `validateValue()` in field config returns false for the value or if input value does not satisfy `max`, `min` constraints in `fieldSettings`
 |canReorder |true |Activate reordering support for rules and groups of rules?
 |canRegroup |true |Allow move rules (or groups) in/out groups during reorder? +
   False - allow "safe" reorder, means only reorder at same level
@@ -336,9 +339,10 @@ Behaviour settings:
 |showLock |false |Show "Lock" switch for rules and groups to make them read-only ("admin mode") +
   NOTE: To preserve read-only state of rules in JsonLogic, please use `jsonLogic.add_operation("locked", v => v);` in your code
 |canDeleteLocked |false |Show "Delete" button for locked rule?
-|removeIncompleteRulesOnLoad |true |Remove incomplete rules (w/o value) during validation in `Utils.checkTree()`?
-|removeEmptyGroupsOnLoad |true |Remove empty groups during validation in `Utils.checkTree()`?
-|removeInvalidMultiSelectValuesOnLoad |true |Remove values that are not in `listValues` during validation in `Utils.checkTree()`? +
+|removeIncompleteRulesOnLoad |false |Remove incomplete rules (without field, operator, value, or if not all required args are present for functin) during initial validation of `value` prop passed to `<Query>`
+|removeEmptyRulesOnLoad |true |Remove empty rules during initial validation of `value` prop passed to `<Query>`
+|removeEmptyGroupsOnLoad |true |Remove empty groups during initial validation of `value` prop passed to `<Query>`
+|removeInvalidMultiSelectValuesOnLoad |true |Remove values that are not in `listValues` during initial validation of `value` prop passed to `<Query>`? +
   By default `true`, but `false` for AntDesign as can be removed manually
 |useConfigCompress |false |Set to `true` if you use `Utils.decompressConfig()`
 |fieldItemKeysForSearch |`["label", "path", "altLabel", "grouplabel"]` |Keys in field item (see {d_ts}[type] `FieldItem`) available for search. Available keys: "key", "path", "label", "altLabel" (label2), "tooltip", "grouplabel" (label of parent group, for subfields of complex fields)

CONTRIBUTING.md

@@ -1,19 +1,34 @@
 # Contributing
 
-Feel free to open PRs to fix bugs, add new features, add new reusable types/widgets/operators (eg., regex operator/widget, IP type/widget).  
+Feel free to open PRs to fix bugs, add new features, add new reusable types/widgets/operators (eg., regex operator/widget, IP type/widget etc.).  
 
 * [Development](#development)
   * [Directory structure](#directory-structure) 
   * [Scripts](#scripts)
   * [Other UI frameworks](#other-ui-frameworks)
+* [Tests](#tests)
 
 
 ## Development
-Clone this repo, install `npm 7+` and run `npm start`. 
-Open `http://localhost:3001/` in a browser. 
-You will see demo app with hot reload of demo code and local library code. 
+
+We use [pnpm](https://pnpm.io/). Please [install pnpm](https://pnpm.io/installation):
+```
+npm install -g pnpm
+```
+Clone this repo, install deps with `pnpm i`.
+
+Start with the demo app (with hot reload of demo code and local library code):
+- Run `pnpm start`. 
+- Open `http://localhost:3001/` in a browser. 
+
+Or with VSCode:
+- Open `Run and Debug` in VS Code
+- Run `Run examples`
+- Run `Open Chrome with examples`
+
 
 ### Directory structure
+
 - [`packages/core/modules`](/packages/core/modules) - Core functionality, does not depend from React
   - [`config`](/packages/core/modules/config) - Core config. See [`CONFIG`](/CONFIG.adoc) docs.
   - [`export`](/packages/core/modules/export) - Code for export to JsonLogic, MongoDb, SQL, ElasticSearch, plain string, SpEL
@@ -48,15 +63,15 @@ You will see demo app with hot reload of demo code and local library code.
 - [`packages/tests`](/packages/tests) - All tests are here. Uses Karma, Mocha, Chai, Enzyme
 
 ### Scripts
-We use [pnpm](https://pnpm.io/). Please [install pnpm](https://pnpm.io/installation):
-```
-npm install -g pnpm
-```
 
 Useful scripts:
 - `pnpm i` - Install packages in all workspaces. **Required for other scripts!**
+- `pnpm start` - Run [`examples`](/packages/examples)
 - `pnpm build` - Build all packages and examples
-- `pnpm test` - Run tests with Karma and update coverage.
+- `pnpm test` - Run all tests with Karma and update coverage.
+- `pnpm test-dev` - Run all tests with Karma in watch mode.
+- `pnpm test-debug` - Run tests with Karma in watch & debug mode.
+- `pnpm test-debug --filter Validation WidgetsVanilla` - Run only selected tests with Karma.
 - `pnpm lint` - Run ESLint and TSC (in all workspaces)
 - `pnpm lint-fix` - Run ESLint with `--fix` option (in in all workspaces)
 - `pnpm clean` - Clean all data that can be re-generated (like `node_modules`, `build`, `coverage`)
@@ -66,6 +81,7 @@ Feel free to open PR to add new reusable types/widgets/operators (eg., regex ope
 Pull Requests are always welcomed :)
 
 ### Other UI frameworks
+
 Currently there are 5 collections of widgets:
 - [vanilla widgets](/packages/ui/modules/components/widgets/vanilla)
 - [antdesign widgets](/packages/antd)
@@ -80,3 +96,7 @@ Create new package `@react-awesome-query-builder/x` in [packages](/packages).
 For a playground integrate it in [examples](/packages/examples) - add to `dependecies` in [package.json](/packages/examples/package.json), `paths` in [tsconfig.json](/packages/examples/tsconfig.json), `aliases` in [webpack.config.js](/packages/examples/webpack.config.js), `skinToConfig` in [config.tsx](/packages/examples/demo/config.tsx).
 
 Take [PR #727 to add Fluent UI widgets](https://github.com/ukrbublik/react-awesome-query-builder/pull/727) as an example.
+
+## Tests
+
+See [tests readme](/packages/tests)