Add context provider documentation for companion/compat packages

Author: jakeboone02

docs/api/misc.mdx

@@ -8,6 +8,8 @@ import TypeScriptAdmonition from './_ts_admonition.md';
 
 <TypeScriptAdmonition />
 
+A non-comprehensive list of exports from `react-querybuilder`.
+
 ## Utilities
 
 ### `defaultValidator`
@@ -85,6 +87,7 @@ 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
+- `InlineCombinator` - used when either `showCombinatorsBetweenRules` or `independentCombinators` are `true`
 - `NotToggle` - used for the "Invert this group" toggle switch
 - `Rule` - the default rule component
 - `RuleGroup` - the default rule group component

docs/api/querybuilder.mdx

@@ -780,24 +780,39 @@ When the `independentCombinators` option is enabled, the `query` (or `defaultQue
 
 `boolean` (default `false`) [_Click for demo_](https://react-querybuilder.js.org/react-querybuilder/#enableDragAndDrop=true)
 
-Pass `true` to display a drag handle to the left of each group header and rule. Clicking and dragging the handle element allows visual reordering of rules and groups.
+:::caution
+
+This prop does not need to be set directly. If used directly, it has no effect unless the following conditions are met:
+
+1. A `QueryBuilderDnD` context provider from the companion package [`@react-querybuilder/dnd`](https://www.npmjs.com/package/@react-querybuilder/dnd) is rendered higher up in the component tree.
+2. [`react-dnd`](https://www.npmjs.com/package/react-dnd) and [`react-dnd-html5-backend`](https://www.npmjs.com/package/react-dnd-html5-backend) are also installed.
 
-Drag-and-drop functionality is only enabled when `<QueryBuilder />` is wrapped in `QueryBuilderDnD` from the companion package [`@react-querybuilder/dnd`](https://www.npmjs.com/package/@react-querybuilder/dnd). [`react-dnd`](https://www.npmjs.com/package/react-dnd) and [`react-dnd-html5-backend`](https://www.npmjs.com/package/react-dnd-html5-backend) will also need to be installed.
+If those conditions are met, and `enableDragAndDrop` is not explicitly set to `false` on the `<QueryBuilder />` element, then `enableDragAndDrop` is implicitly set to `true`.
+
+:::
+
+When `true` (under the conditions detailed above), a drag handle is displayed on the left-hand side of each group header and each rule. Clicking and dragging the handle element allows users to visually reorder the rules and groups.
+
+#### Example usage
+
+```bash
+yarn add react-querybuilder @react-querybuilder/dnd react-dnd react-dnd-html5-backend
+```
 
 ```tsx
 import { QueryBuilderDnD } from '@react-querybuilder/dnd';
 import { QueryBuilder } from 'react-querybuilder';
 
 const App = () => (
   <QueryBuilderDnD>
-    <QueryBuilder enableDragAndDrop />
+    <QueryBuilder />
   </QueryBuilderDnD>
 );
 ```
 
 :::tip
 
-If your application already uses [`react-dnd`](https://react-dnd.github.io/react-dnd/), wrap `<QueryBuilder />` in `QueryBuilderWithoutDndProvider` instead of `QueryBuilderDnD`. They add the same functionality, but the former will rely on your pre-existing `<DndProvider />`. The latter implements its own provider and will clash with a separate `<DndProvider />` higher up in the component tree. (If you use the wrong component, you will probably see the error message "Cannot have two HTML5 backends at the same time.")
+If your application already uses [`react-dnd`](https://react-dnd.github.io/react-dnd/), use `QueryBuilderWithoutDndProvider` instead of `QueryBuilderDnD`. They are functionally equivalent, but the former relies on your pre-existing `<DndProvider />` (as long as it is higher up in the component tree). The latter renders its own provider which will clash with an ancestor `DndProvider`. (If you use the wrong component, you will probably see the error message "Cannot have two HTML5 backends at the same time.")
 
 :::
 

docs/compat.mdx

@@ -2,13 +2,13 @@
 title: Compatibility packages
 ---
 
-The default React Query Builder components, being basic HTML5 form controls, are very flexible when it comes to styling (primarily through the [`controlClassnames` prop](./api/querybuilder#controlclassnames)). But some style libraries require different HTML structure to style their form controls correctly.
+The default React Query Builder components, being basic HTML5 form controls, are very flexible when it comes to styling (primarily through the [`controlClassnames` prop](./api/querybuilder#controlclassnames)). However, some style libraries require different HTML structure to style their form controls correctly.
 
 ## Packages
 
 Official component packages compatible with several popular style libraries are available under the [`@react-querybuilder` org on npm](https://www.npmjs.com/org/react-querybuilder).
 
-You can see each alternate component package in action by selecting different options in the "Style" dropdown list on the [demo page](https://react-querybuilder.js.org/react-querybuilder/). The "Demo" links in the table below will load the demo with the respective style library preselected, and the CodeSandbox links will open [codesandbox.io](https://codesandbox.io) with an editable example of the library preloaded.
+You can see each alternate component package in action by selecting different options in the "Style" dropdown list on the [demo page](https://react-querybuilder.js.org/react-querybuilder/). The "Demo" links in the table below will load the demo with the respective style library preselected, and the CodeSandbox links will open [codesandbox.io](https://codesandbox.io) with a live, editable example of the library preloaded.
 
 | Official site                          | Compatibility package                                                                        | Demo                                                                          | CodeSandbox                                                                                                       |
 | -------------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
@@ -18,9 +18,68 @@ You can see each alternate component package in action by selecting different op
 | [Chakra UI](https://chakra-ui.com/)    | [@react-querybuilder/chakra](https://www.npmjs.com/package/@react-querybuilder/chakra)       | [Demo](https://react-querybuilder.js.org/react-querybuilder/#style=chakra)    | [CodeSandbox](https://codesandbox.io/s/github/react-querybuilder/react-querybuilder/tree/main/examples/chakra)    |
 | [MUI](https://mui.com/)                | [@react-querybuilder/material](https://www.npmjs.com/package/@react-querybuilder/material)   | [Demo](https://react-querybuilder.js.org/react-querybuilder/#style=material)  | [CodeSandbox](https://codesandbox.io/s/github/react-querybuilder/react-querybuilder/tree/main/examples/material)  |
 
-## Exports
+## Usage
 
-Each compatibility package exports a `*ControlElements` object that can be used as the [`controlElements` prop](./api/querybuilder#controlelements) in `<QueryBuilder />`. Some packages also export a `*ControlClassnames` object for use as the [`controlClassnames` prop](./api/querybuilder#controlclassnames).
+The recommended way to apply a compatibility package to `<QueryBuilder />` is to wrap it in the `QueryBuilder*` context provider from the compatibility library.
+
+This example uses the Ant Design library:
+
+```tsx
+import { QueryBuilderAntD } from '@react-querybuilder/antd';
+import 'antd/dist/antd.compact.css';
+import { QueryBuilder } from 'react-querybuilder';
+import 'react-querybuilder/dist/query-builder.css';
+import { defaultQuery, fields } from './constants';
+
+export function App() {
+  return (
+    <QueryBuilderAntD>
+      <QueryBuilder fields={fields} defaultQuery={defaultQuery} />
+    </QueryBuilderAntD>
+  );
+}
+```
+
+Each compatibility package exports its own context provider.
+
+| Compatibility package           | Context provider        |
+| ------------------------------- | ----------------------- |
+| `@react-querybuilder/antd`      | `QueryBuilderAntD`      |
+| `@react-querybuilder/bootstrap` | `QueryBuilderBootstrap` |
+| `@react-querybuilder/bulma`     | `QueryBuilderBulma`     |
+| `@react-querybuilder/chakra`    | `QueryBuilderChakra`    |
+| `@react-querybuilder/material`  | `QueryBuilderMaterial`  |
+
+:::tip
+
+React Query Builder context providers can be nested beneath one another to progressively add features and customization. For example, `QueryBuilderDnD` adds drag-and-drop features to the query builder, and you can nest the compatibility package context providers beneath it (or vice versa) to add the style library's components while maintaining the drag-and-drop features.
+
+This example uses the Bulma library _and_ enables drag-and-drop:
+
+```tsx
+import { QueryBuilderBulma } from '@react-querybuilder/bulma';
+import { QueryBuilderDnD } from '@react-querybuilder/dnd';
+import 'bulma/bulma.sass';
+import { QueryBuilder } from 'react-querybuilder';
+import 'react-querybuilder/dist/query-builder.css';
+import { defaultQuery, fields } from './constants';
+
+export function App() {
+  return (
+    <QueryBuilderDnD>
+      <QueryBuilderBulma>
+        <QueryBuilder fields={fields} defaultQuery={defaultQuery} />
+      </QueryBuilderBulma>
+    </QueryBuilderDnD>
+  );
+}
+```
+
+:::
+
+## Other exports
+
+Each compatibility package exports a `*ControlElements` object that can be used as the [`controlElements` prop](./api/querybuilder#controlelements) in `<QueryBuilder />`. Some packages also export a `*ControlClassnames` object for use with the [`controlClassnames` prop](./api/querybuilder#controlclassnames). Use these exports if you need more fine-grained control over which standard components get replaced. For even more detailed [customization](#customization), continue reading below.
 
 This example uses the Bootstrap library:
 
@@ -29,8 +88,8 @@ import {
   bootstrapControlClassnames,
   bootstrapControlElements,
 } from '@react-querybuilder/bootstrap';
-import { QueryBuilder } from 'react-querybuilder';
 import 'bootstrap/scss/bootstrap.scss';
+import { QueryBuilder } from 'react-querybuilder';
 import { defaultQuery, fields } from './constants';
 
 export function App() {
@@ -47,11 +106,11 @@ export function App() {
 
 ## Customization
 
-Many of the compatibility components accept any props defined by the style library for the actual rendered component in addition to the standard props defined by `react-querybuilder`. This allows you to idiomatically customize the library component while leaving the integration with the query builder up to the compatibility component.
+Many of the compatibility components accept props defined by the style library for the actual rendered component in addition to the standard props defined by `react-querybuilder`. This allows you to idiomatically customize the style library's component while leaving the query builder integration up to the compatibility layer.
 
 For example, the `AntDActionElement` component from `@react-querybuilder/antd` renders the `Button` component from `antd`, so it can accept properties of the `ActionWithRulesProps` interface from `react-querybuilder` _and_ the `ButtonProps` interface from `antd`.
 
-In the example below, the `size` prop is not available on `ActionWithRulesProps`, but it's accepted because it's one of `antd`'s `Button` props (from the `ButtonProps` interface).
+In the example below, the `size` prop is accepted because it's one of `antd`'s `Button` props (from the `ButtonProps` interface), even though it's not included in the `ActionWithRulesProps` interface.
 
 ```tsx
 import { AntDActionElement, antdControlElements } from '@react-querybuilder/antd';
@@ -82,7 +141,7 @@ export const App = () => {
 
 This list shows which library components' props will be accepted by the compatibility components, in addition to those defined by `react-querybuilder`.
 
-| Compatibility component | Base props               | Rendered library component                                      |
+| Component               | Base props (from RQB)    | Rendered library component                                      |
 | ----------------------- | ------------------------ | --------------------------------------------------------------- |
 | `AntDActionElement`     | `ActionWithRulesProps`   | `import { Button } from 'antd'`                                 |
 | `AntDDragHandle`        | `DragHandleProps`        | `import { HolderOutlined } from '@ant-design/icons'`            |

docs/tips/common-mistakes.mdx

@@ -32,7 +32,7 @@ const App = () => {
 };
 ```
 
-This is wrong and can lead to undesirable behavior, such as the value editor losing focus after each keystroke. This happens because the `CustomValueEditor` component is being redefined each time the `App` component renders. Fortunately, the fix is very simple: move the custom component declaration outside of the other function component (it can still be in the same file, just not within the function body):
+This can lead to undesirable behavior, such as the value editor losing focus after each keystroke. This happens because the `CustomValueEditor` component is being redefined each time the `App` component renders. To fix the problem, move the custom component declaration outside of the other function component (it can still be in the same file, just not within the function body):
 
 ```tsx title="App.tsx"
 // highlight-start

versioned_docs/version-4.5.2/tips/common-mistakes.mdx

@@ -32,7 +32,7 @@ const App = () => {
 };
 ```
 
-This is wrong and can lead to undesirable behavior, such as the value editor losing focus after each keystroke. This happens because the `CustomValueEditor` component is being redefined each time the `App` component renders. Fortunately, the fix is very simple: move the custom component declaration outside of the other function component (it can still be in the same file, just not within the function body):
+This can lead to undesirable behavior, such as the value editor losing focus after each keystroke. This happens because the `CustomValueEditor` component is being redefined each time the `App` component renders. To fix the problem, move the custom component declaration outside of the other function component (it can still be in the same file, just not within the function body):
 
 ```tsx title="App.tsx"
 // highlight-start