Documentation for RQB 4.2.0

docs/api/classnames.mdx

@@ -0,0 +1,143 @@
+---
+title: CSS classes
+hide_table_of_contents: true
+description: Visual guide to CSS classes for each component element
+---
+
+The `<QueryBuilder />` component assigns [standard classes](./misc#defaults) to each element. In the (fully operational) query builder below, the `title` and `label` for each element have been set to the element's standard class.
+
+The following standard classnames are not visible below:
+
+- `.queryBuilder` (black outline; the outer-most `<div>`)
+- `.ruleGroup` (maroon outline)
+- `.ruleGroup-header` (purple outline)
+- `.ruleGroup-body` (blue outline)
+- `.rule.queryBuilder-disabled` (gray outline for locked/disabled rules)
+- `.rule.queryBuilder-valid` (green outline for valid rules)
+- `.rule.queryBuilder-invalid` (red outline for invalid rules)
+- `.dndDragging` (applied to "preview" element while dragging)
+- `.dndOver` (applied to "hovered over" element while dragging)
+
+import { QueryBuilderEmbed } from '../../src/components/QueryBuilderEmbed';
+import { standardClassnames as sc } from 'react-querybuilder';
+
+<QueryBuilderEmbed
+  showNotToggle
+  showCloneButtons
+  showLockButtons
+  enableDragAndDrop
+  fields={[
+    {
+      name: 'f1',
+      label: `.${sc.fields}`,
+      defaultValue: 'This rule is valid',
+      validator: () => true,
+    },
+    {
+      name: 'f2',
+      label: `.${sc.fields}`,
+      defaultValue: 'This rule is invalid',
+      validator: () => false,
+    },
+    {
+      name: 'f3',
+      label: `.${sc.valueSource}`,
+      valueSources: ['value', 'field'],
+    },
+  ]}
+  combinators={[{ name: 'and', label: `.${sc.combinators}` }]}
+  getOperators={() => [{ name: '=', label: `.${sc.operators}` }]}
+  controlClassnames={{
+    queryBuilder: 'rqb-structure',
+  }}
+  translations={{
+    fields: {
+      title: `.${sc.fields}`,
+    },
+    operators: {
+      title: `.${sc.operators}`,
+    },
+    value: {
+      title: `.${sc.value}`,
+    },
+    removeRule: {
+      label: `.${sc.removeRule}`,
+      title: `.${sc.removeRule}`,
+    },
+    removeGroup: {
+      label: `.${sc.removeGroup}`,
+      title: `.${sc.removeGroup}`,
+    },
+    addRule: {
+      label: `.${sc.addRule}`,
+      title: `.${sc.addRule}`,
+    },
+    addGroup: {
+      label: `.${sc.addGroup}`,
+      title: `.${sc.addGroup}`,
+    },
+    combinators: {
+      title: `.${sc.combinators}`,
+    },
+    notToggle: {
+      label: `.${sc.notToggle}`,
+      title: `.${sc.notToggle}`,
+    },
+    cloneRule: {
+      label: `.${sc.cloneRule}`,
+      title: `.${sc.cloneRule}`,
+    },
+    cloneRuleGroup: {
+      label: `.${sc.cloneGroup}`,
+      title: `.${sc.cloneGroup}`,
+    },
+    dragHandle: {
+      label: `.${sc.dragHandle}`,
+      title: `.${sc.dragHandle}`,
+    },
+    lockRule: {
+      label: `.${sc.lockRule}`,
+      title: `.${sc.lockRule}`,
+    },
+    lockGroup: {
+      label: `.${sc.lockGroup}`,
+      title: `.${sc.lockGroup}`,
+    },
+    lockRuleDisabled: {
+      label: `.${sc.lockRuleDisabled}`,
+      title: `.${sc.lockRuleDisabled}`,
+    },
+    lockGroupDisabled: {
+      label: `.${sc.lockGroupDisabled}`,
+      title: `.${sc.lockGroupDisabled}`,
+    },
+    valueSourceSelector: {
+      title: `.${sc.valueSource}`,
+    },
+  }}
+  defaultQuery={{
+    combinator: 'and',
+    rules: [
+      { field: 'f1', operator: '=', value: `.${sc.value}` },
+      {
+        combinator: 'and',
+        rules: [
+          { field: 'f1', operator: '=', value: 'This rule is valid' },
+          { field: 'f2', operator: '=', value: 'This rule is invalid' },
+          {
+            disabled: true,
+            combinator: 'and',
+            rules: [
+              {
+                field: 'f1',
+                operator: '=',
+                value: `This rule's group is disabled, therefore this rule is also disabled`,
+              },
+            ],
+          },
+        ],
+      },
+      { field: 'f3', operator: '=', value: 'f1' },
+    ],
+  }}
+/>

docs/api/export.mdx

@@ -233,6 +233,32 @@ The `fallbackExpression` is a string that will be part of the output when `forma
 
 By default, `fallbackExpression` is `"(1 = 1)"` for the "sql", "parameterized", and "parameterized_named" formats, and `"{$and:[{$expr:true}]}"` for the "mongodb" format.
 
+### Value sources
+
+When the `valueSource` property for a rule is set to "field", `formatQuery` will place the bare, unquoted value (which should be a valid field name) in the result for the "sql", "parameterized", "parameterized_named", and "mongodb" formats. No parameters will be generated for such rules.
+
+```ts
+const pf = formatQuery(
+  {
+    combinator: 'and',
+    rules: [
+      { field: 'firstName', operator: '=', value: 'lastName', valueSource: 'field' },
+      { field: 'firstName', operator: 'beginsWith', value: 'middleName', valueSource: 'field' },
+    ],
+  },
+  'parameterized_named'
+);
+```
+
+Output:
+
+```ts
+{
+  sql: "(firstName = lastName and firstName like middleName || '%')",
+  params: {},
+}
+```
+
 ## 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.

docs/api/import.mdx

@@ -66,7 +66,11 @@ To generate actual arrays instead of comma-separated strings for lists of values
 parseSQL(`SELECT * FROM t WHERE lastName IN ('Vai', 'Vaughan') AND age BETWEEN 20 AND 100`, {
   listsAsArrays: true;
 });
-// Output:
+```
+
+Output:
+
+```ts
 {
   combinator: "and",
   rules: [
@@ -113,3 +117,41 @@ Output (`RuleGroupTypeIC`):
   ];
 }
 ```
+
+## Fields as value source
+
+When the `fields` option (which accepts the same types as the [`fields` prop](./querybuilder#fields)) is provided, and _only_ if it is provided, then `parseSQL` will validate clauses that have a field identifier to the right of the operator instead of a primitive value. A `getValueSources` function can also be provided to help validate rules.
+
+In order for such a rule to be considered valid, either the `getValueSources` return value, the field's `valueSources` property return value, or the field's `valueSources` property itself must be an array that includes the string "field".
+
+```ts
+parseSQL(`SELECT * FROM t WHERE firstName = lastName`, {
+  fields: [
+    { name: 'firstName', label: 'First Name' },
+    { name: 'lastName', label: 'Last Name' },
+  ],
+  getValueSources: () => ['value', 'field'],
+});
+```
+
+Output:
+
+```ts
+{
+  combinator: "and",
+  rules: [
+    {
+      field: "firstName",
+      operator: "=",
+      value: "lastName",
+      valueSource: "field",
+    },
+  ],
+}
+```
+
+:::note
+
+`parseSQL` will only validate clauses where "field" is the _only_ value source. Operators that take multiple values, like "between" and "in", must only have field names to the right of the operator, not a mix of field names and primitive values.
+
+:::

docs/api/misc.mdx

@@ -42,19 +42,30 @@ function convertQuery(query: RuleGroupTypeIC): RuleGroupType;
 
 `convertToIC` and `convertFromIC` do the same thing as `convertQuery`, but only in one direction.
 
-### Defaults
+## Query tools
+
+Several methods are available to assist with manipulation of query objects outside the context of the `<QueryBuilder />` component:
+
+- `add` - adds a rule or group (and an independent combinator if necessary to keep the query valid)
+- `remove` - removes a rule or group (and the previous independent combinator if one exists)
+- `update` - updates a property of a rule or group, or updates an independent combinator
+- `move` - moves (or clones, with new `id` and `path`) a rule or group to a new location in the query tree
+
+These methods are used by the `<QueryBuilder />` component itself, so they are guaranteed to achieve the same result as a corresponding UI-based update.
+
+## Defaults
 
 The following default configuration objects are exported for convenience.
 
-- `defaultCombinators`
-- `defaultOperators`
-- `defaultTranslations`
-- `defaultValueProcessor`
-- `defaultMongoDBValueProcessor`
-- `defaultFields`
-- `standardClassnames`
+- `defaultCombinators` (see [`combinators` prop](./querybuilder#combinators))
+- `defaultOperators` (see [`operators` prop](./querybuilder#operators))
+- `defaultTranslations` (see [`translations` prop](./querybuilder#translations))
+- `defaultValueProcessor` (see [Export](./export) > [Value processor](./export#value-processor))
+- `defaultMongoDBValueProcessor` (see [Export](./export) > [Value processor](./export#value-processor))
+- `defaultFields` (see [`fields` prop](./querybuilder#fields))
+- `standardClassnames` (see [CSS classes](./classnames))
 
-The following components are also exported:
+The default components are also exported:
 
 - `ActionElement` - used for action buttons (to add rules, remove groups, etc.)
 - `DragHandle` - used for the drag handle on rules and group headers