Merge pull request #10 from react-querybuilder/v430

Documentation changes for v4.3.1

Author: jakeboone02

docs/api/export.mdx

@@ -122,10 +122,10 @@ formatQuery(query, 'parameterized');
 
 Output:
 
-```ts
+```json
 {
-  sql: "(firstName = ? and lastName = ?)",
-  params: ["Steve", "Vai"]
+  "sql": "(firstName = ? and lastName = ?)",
+  "params": ["Steve", "Vai"]
 }
 ```
 
@@ -139,12 +139,12 @@ formatQuery(query, 'parameterized_named');
 
 Output:
 
-```ts
+```json
 {
-  sql: "(firstName = :firstName_1 and lastName = :lastName_1)",
-  params: {
-    firstName_1: "Steve",
-    lastName_1: "Vai"
+  "sql": "(firstName = :firstName_1 and lastName = :lastName_1)",
+  "params": {
+    "firstName_1": "Steve",
+    "lastName_1": "Vai"
   }
 }
 ```
@@ -325,13 +325,17 @@ const pf = formatQuery(
 
 Output:
 
-```ts
+```json
 {
-  sql: "(firstName = lastName and firstName like middleName || '%')",
-  params: {},
+  "sql": "(firstName = lastName and firstName like middleName || '%')",
+  "params": {}
 }
 ```
 
+### Placeholder values
+
+Any rule where the `field` or `operator` matches the placeholder value (default `"~"`) will be excluded from the output for most export formats (see [Automatic validation](#automatic-validation)). To use a different string as the placeholder value, set the `fields.placeholderName` and/or the `operators.placeholderName` property as appropriate on the [`translations` prop](./querybuilder#translations) object.
+
 ## Validation
 
 The validation options (`validator` and `fields` – see [Validation](./validation) for more information) only affect the output when `format` is "sql", "parameterized", "parameterized_named", or "mongodb". If the `validator` function returns `false`, the `fallbackExpression` will be returned. Otherwise, groups and rules marked as invalid (either by the validation map produced by the `validator` function or the result of the field-based `validator` function) will be ignored.
@@ -383,7 +387,8 @@ formatQuery(query, {
 
 ### Automatic validation
 
-A basic form of validation will be used by `formatQuery` for the "in", "notIn", "between", and "notBetween" operators when the output format is "sql", "parameterized", "parameterized_named", or "mongodb". This validation is used regardless of the presence of any `validator` options either at the query or field level:
+A basic form of validation will be used by `formatQuery` for the "in", "notIn", "between", and "notBetween" operators when the output format is "sql", "parameterized", "parameterized_named", "mongodb", or "cel". This validation is used regardless of the presence of any `validator` options either at the query or field level:
 
 - Rules that specify an "in" or "notIn" `operator` will be deemed invalid if the rule's `value` is neither an array with at least one element (i.e. `value.length > 0`) nor a non-empty string.
 - Rules that specify a "between" or "notBetween" `operator` will be deemed invalid if the rule's `value` is neither an array of length two (`value.length === 2`) nor a string with exactly one comma that isn't the first or last character (i.e. `value.split(',').length === 2` and neither element is an empty string).
+- Rules where the following expression is true will be deemed invalid: `field === placeholderFieldName || operator === placeholderOperatorName`.

docs/api/import.mdx

@@ -40,19 +40,19 @@ parseSQL(`SELECT * FROM t WHERE firstName = $p1 AND lastName = $p2`, {
 
 Output (`RuleGroupType`):
 
-```ts
+```json
 {
-  combinator: "and",
-  rules: [
+  "combinator": "and",
+  "rules": [
     {
-      field: "firstName",
-      operator: "=",
-      value: "Steve"
+      "field": "firstName",
+      "operator": "=",
+      "value": "Steve"
     },
     {
-      field: "lastName",
-      operator: "=",
-      value: "Vai"
+      "field": "lastName",
+      "operator": "=",
+      "value": "Vai"
     }
   ]
 }
@@ -70,19 +70,19 @@ parseSQL(`SELECT * FROM t WHERE lastName IN ('Vai', 'Vaughan') AND age BETWEEN 2
 
 Output:
 
-```ts
+```json
 {
-  combinator: "and",
-  rules: [
+  "combinator": "and",
+  "rules": [
     {
-      field: "lastName",
-      operator: "in",
-      value: ["Vai", "Vaughan"]
+      "field": "lastName",
+      "operator": "in",
+      "value": ["Vai", "Vaughan"]
     },
     {
-      field: "age",
-      operator: "between",
-      value: [20, 100]
+      "field": "age",
+      "operator": "between",
+      "value": [20, 100]
     }
   ]
 }
@@ -100,21 +100,21 @@ parseSQL(`SELECT * FROM t WHERE firstName = 'Steve' AND lastName = 'Vai'`, {
 
 Output (`RuleGroupTypeIC`):
 
-```ts
+```json
 {
-  rules: [
+  "rules": [
     {
-      field: 'firstName',
-      operator: '=',
-      value: 'Steve',
+      "field": "firstName",
+      "operator": "=",
+      "value": "Steve"
     },
-    'and',
+    "and",
     {
-      field: 'lastName',
-      operator: '=',
-      value: 'Vai',
-    },
-  ];
+      "field": "lastName",
+      "operator": "=",
+      "value": "Vai"
+    }
+  ]
 }
 ```
 
@@ -136,17 +136,17 @@ parseSQL(`SELECT * FROM t WHERE firstName = lastName`, {
 
 Output:
 
-```ts
+```json
 {
-  combinator: "and",
-  rules: [
+  "combinator": "and",
+  "rules": [
     {
-      field: "firstName",
-      operator: "=",
-      value: "lastName",
-      valueSource: "field",
-    },
-  ],
+      "field": "firstName",
+      "operator": "=",
+      "value": "lastName",
+      "valueSource": "field"
+    }
+  ]
 }
 ```
 

docs/api/querybuilder.mdx

@@ -588,69 +588,73 @@ interface Classnames {
 
 This prop can be used to override translatable texts applied to various controls that are created by the `<QueryBuilder />` component. All keys in the object and all properties within each key are optional. Missing translations will default to the values below.
 
-```ts
+```json
 {
-  fields: {
-    title: "Fields",
-    placeholderLabel: "------",
-    placeholderGroupLabel: "------",
+  "fields": {
+    "title": "Fields",
+    "placeholderName": "~",
+    "placeholderLabel": "------",
+    "placeholderGroupLabel": "------"
   },
-  operators: {
-    title: "Operators",
+  "operators": {
+    "title": "Operators",
+    "placeholderName": "~",
+    "placeholderLabel": "------",
+    "placeholderGroupLabel": "------"
   },
-  value: {
-    title: "Value",
+  "value": {
+    "title": "Value"
   },
-  removeRule: {
-    label: "x",
-    title: "Remove rule",
+  "removeRule": {
+    "label": "x",
+    "title": "Remove rule"
   },
-  removeGroup: {
-    label: "x",
-    title: "Remove group",
+  "removeGroup": {
+    "label": "x",
+    "title": "Remove group"
   },
-  addRule: {
-    label: "+Rule",
-    title: "Add rule",
+  "addRule": {
+    "label": "+Rule",
+    "title": "Add rule"
   },
-  addGroup: {
-    label: "+Group",
-    title: "Add group",
+  "addGroup": {
+    "label": "+Group",
+    "title": "Add group"
   },
-  combinators: {
-    title: "Combinators",
+  "combinators": {
+    "title": "Combinators"
   },
-  notToggle: {
-    label: "Not",
-    title: "Invert this group",
+  "notToggle": {
+    "label": "Not",
+    "title": "Invert this group"
   },
-  cloneRule: {
-    label: '⧉',
-    title: 'Clone rule'
+  "cloneRule": {
+    "label": "⧉",
+    "title": "Clone rule"
   },
-  cloneRuleGroup: {
-    label: '⧉',
-    title: 'Clone group'
+  "cloneRuleGroup": {
+    "label": "⧉",
+    "title": "Clone group"
   },
-  dragHandle: {
-    label: '⁞⁞',
-    title: 'Drag handle'
+  "dragHandle": {
+    "label": "⁞⁞",
+    "title": "Drag handle"
   },
-  lockRule: {
-    label: '🔓',
-    title: 'Lock rule',
+  "lockRule": {
+    "label": "🔓",
+    "title": "Lock rule"
   },
-  lockGroup: {
-    label: '🔓',
-    title: 'Lock group',
+  "lockGroup": {
+    "label": "🔓",
+    "title": "Lock group"
   },
-  lockRuleDisabled: {
-    label: '🔒',
-    title: 'Unlock rule',
+  "lockRuleDisabled": {
+    "label": "🔒",
+    "title": "Unlock rule"
   },
-  lockGroupDisabled: {
-    label: '🔒',
-    title: 'Unlock group',
+  "lockGroupDisabled": {
+    "label": "🔒",
+    "title": "Unlock group"
   }
 }
 ```
@@ -699,7 +703,13 @@ Pass `false` to disable the `onQueryChange` call on mount of the component which
 
 `boolean` (default `true`) [_Click for demo with this feature disabled_](https://react-querybuilder.js.org/react-querybuilder/#autoSelectField=false)
 
-Pass `false` to automatically add an "empty" option with label `"------"` (or `translations.fields.placeholderLabel` if provided--see [translations](#translations)) to the `fields` array as the first element. The empty option will be the initial selection for all new rules. When the empty field option is selected, the operator and value components will not display for that rule.
+Pass `false` to automatically add an "empty" option with value `"~"` and label `"------"` (see [`translations.fields.placeholder*` to customize](#translations)) to the `fields` array as the first element. The empty option will be the initial selection for all new rules. When the empty field option is selected, the operator and value editor components will not display for that rule.
+
+### `autoSelectOperator`
+
+`boolean` (default `true`) [_Click for demo with this feature disabled_](https://react-querybuilder.js.org/react-querybuilder/#autoSelectOperator=false)
+
+Pass `false` to automatically add an "empty" option with value `"~"` and label `"------"` (see [`translations.operators.placeholder*` to customize](#translations)) to the `operators` array as the first element. The empty option will be the initial selection for all new rules. When the empty operator option is selected, the value editor component will not display for that rule.
 
 ### `addRuleToNewGroups`
 

docs/api/validation.mdx

@@ -16,7 +16,7 @@ Validating at the query level can result in the entire query being treated as va
 To mark an entire query as valid or invalid, return a `boolean` value from the `validator` callback function (`true` for valid, `false` for invalid).
 
 ```tsx
-import QueryBuilder, { RuleGroupType } from 'react-querybuilder';
+import { QueryBuilder, RuleGroupType } from 'react-querybuilder';
 
 /**
  * This function returns false (indicating "invalid") if there are no rules present.
@@ -31,7 +31,7 @@ const App = () => {
 The alternate return value from a query-level validator is a validation map, which is an object where each key represents the `id` of a rule or group. Associated values are either `boolean` (`true` for valid, `false` for invalid) or a validation result. Validation results are objects with two keys: a required `boolean` `valid` key and an optional `reasons` array specifying why that rule/group is valid or invalid. (Reasons are assumed to be strings, but the type is `any[]` since the QueryBuilder default components ignore them. Feel free to use them any way you please in your custom components.)
 
 ```tsx
-import QueryBuilder, { RuleGroupType, ValidationMap } from 'react-querybuilder';
+import { QueryBuilder, RuleGroupType, ValidationMap } from 'react-querybuilder';
 
 /**
  * This function returns a validation map. A real validator function would
@@ -67,7 +67,8 @@ Assigning a `validator` to individual fields allows you to provide a separate ca
 In the following configuration, any rule that specifies `field1` as the field (e.g. the second rule) will be marked invalid.
 
 ```tsx
-import QueryBuilder, {
+import {
+  QueryBuilder,
   Field,
   RuleGroupType,
   RuleValidator,