Merge pull request #15 from react-querybuilder/versioned-docs

Versioned docs

Author: jakeboone02

.github/workflows/gh-pages.yml

@@ -17,7 +17,7 @@ jobs:
           node-version: '16.x'
       - name: Test Build
         run: |
-          yarn install --frozen-lockfile
+          yarn install --immutable
           npm run build
   gh-release:
     if: github.event_name != 'pull_request'
@@ -37,5 +37,5 @@ jobs:
         run: |
           git config --global user.email "jakeboone02@gmail.com"
           git config --global user.name "Jake Boone"
-          yarn install --frozen-lockfile
+          yarn install --immutable
           npm run deploy

.gitignore

@@ -18,3 +18,11 @@
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/sdks
+!.yarn/versions

.yarn/plugins/@yarnpkg/plugin-interactive-tools.cjs

@@ -0,0 +1,9 @@
+nodeLinker: node-modules
+
+plugins:
+  - path: .yarn/plugins/@yarnpkg/plugin-typescript.cjs
+    spec: "@yarnpkg/plugin-typescript"
+  - path: .yarn/plugins/@yarnpkg/plugin-interactive-tools.cjs
+    spec: "@yarnpkg/plugin-interactive-tools"
+
+yarnPath: .yarn/releases/yarn-3.2.3.cjs

.yarn/plugins/@yarnpkg/plugin-typescript.cjs

@@ -8,6 +8,8 @@ import TypeScriptAdmonition from './_ts_admonition.md';
 
 <TypeScriptAdmonition />
 
+A non-comprehensive list of exports from `react-querybuilder`.
+
 ## Utilities
 
 ### `defaultValidator`
@@ -40,7 +42,7 @@ function convertQuery(query: RuleGroupTypeIC): RuleGroupType;
 
 `convertQuery` toggles a query between the conventional `RuleGroupType` structure (with combinators at the group level) and the "independent combinators" structure (`RuleGroupTypeIC`, used with the [`independentCombinators` prop](./querybuilder#independentcombinators)).
 
-`convertToIC` and `convertFromIC` do the same thing as `convertQuery`, but only in one direction.
+`convertToIC` and `convertFromIC` do the same thing as `convertQuery`, but only in the directions indicated by their respective names.
 
 ### `transformQuery`
 
@@ -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

.yarn/releases/yarn-3.2.3.cjs

@@ -171,11 +171,12 @@ The array of combinators that should be used for RuleGroups. The default set inc
 
 ```ts
 interface Controls {
-  addGroupAction?: React.ComponentType<ActionWithRulesProps>;
-  addRuleAction?: React.ComponentType<ActionWithRulesProps>;
+  addGroupAction?: React.ComponentType<ActionWithRulesAndAddersProps>;
+  addRuleAction?: React.ComponentType<ActionWithRulesAndAddersProps>;
   cloneGroupAction?: React.ComponentType<ActionWithRulesProps>;
   cloneRuleAction?: React.ComponentType<ActionProps>;
   combinatorSelector?: React.ComponentType<CombinatorSelectorProps>;
+  inlineCombinator: ComponentType<InlineCombinatorProps>;
   dragHandle?: React.ForwardRefExoticComponent<
     DragHandleProps & React.RefAttributes<HTMLSpanElement>
   >;
@@ -198,11 +199,11 @@ This is a custom controls object that allows you to override the default control
 By default a `<button />` is used. The following props are passed:
 
 ```ts
-interface ActionWithRulesProps {
+interface ActionWithRulesAndAddersProps {
   label: string; // translations.addGroup.label, e.g. "+Group"
   title: string; // translations.addGroup.title, e.g. "Add group"
   className: string; // CSS classNames to be applied
-  handleOnClick: (e: React.MouseEvent) => void; // Callback function to invoke adding a <RuleGroup />
+  handleOnClick: (e: React.MouseEvent, context?: any) => void; // Callback function to invoke adding a <RuleGroup />
   rules: (RuleGroupType | RuleType)[]; // Provides the number of rules already present for this group
   level: number; // The level of the current group
   context: any; // Container for custom props that are passed to all components
@@ -266,11 +267,11 @@ interface ActionWithRulesProps {
 By default a `<button />` is used. The following props are passed:
 
 ```ts
-interface ActionWithRulesProps {
+interface ActionWithRulesAndAddersProps {
   label: string; // translations.addGroup.label, e.g. "+Rule"
   title: string; // translations.addGroup.title, e.g. "Add rule"
   className: string; // CSS classNames to be applied
-  handleOnClick: (e: React.MouseEvent) => void; // Callback function to invoke adding a <RuleGroup />
+  handleOnClick: (e: React.MouseEvent, context?: any) => void; // Callback function to invoke adding a <RuleGroup />
   rules: (RuleGroupType | RuleType)[]; // Provides the number of rules already present for this group
   level: number; // The level of the current group
   context: any; // Container for custom props that are passed to all components
@@ -343,6 +344,19 @@ interface CombinatorSelectorProps {
 }
 ```
 
+#### `inlineCombinator`
+
+A small wrapper around the `combinatorSelector` component. The following props are passed:
+
+```ts
+interface InlineCombinatorProps extends CombinatorSelectorProps {
+  component: Schema['controls']['combinatorSelector'];
+  path: number[];
+  moveRule: QueryActions['moveRule'];
+  independentCombinators?: boolean;
+}
+```
+
 #### `dragHandle`
 
 By default a `<span />` is used. Note that this component must be based on `React.forwardRef`, and must always render an element (i.e. never return `null`). The following props are passed:
@@ -536,9 +550,9 @@ This function returns the default value for new rules.
 
 ### `onAddRule`
 
-`(rule: RuleType, parentPath: number[], query: RuleGroupTypeAny) => RuleType | false`
+`(rule: RuleType, parentPath: number[], query: RuleGroupTypeAny, context?: any) => RuleType | false`
 
-This callback is invoked before a new rule is added. The function should either manipulate the rule and return it as an object of type `RuleType`, or return `false` to cancel the addition of the rule. You can use [`findPath`](./misc#findpath) to locate the parent group to which the new rule will be added within the query hierarchy.
+This callback is invoked before a new rule is added. The function should either manipulate the rule and return it as an object of type `RuleType`, or return `false` to cancel the addition of the rule. You can use [`findPath`](./misc#findpath) to locate the parent group to which the new rule will be added within the query hierarchy. The `context` parameter (fourth argument) can be passed from a custom [`addRuleAction`](#addruleaction) component to its `onHandleClick` callback prop, which will in turn pass it to `onAddRule`. This allows one to change the rule that gets added (or avoid the action completely) based on arbitrary information.
 
 :::tip
 
@@ -548,9 +562,9 @@ To completely [prevent the addition of new rules](../tips/limit-groups), pass `c
 
 ### `onAddGroup`
 
-`<RG extends RuleGroupTypeAny>(ruleGroup: RG, parentPath: number[], query: RG) => RG | false`
+`<RG extends RuleGroupTypeAny>(ruleGroup: RG, parentPath: number[], query: RG, context?: any) => RG | false`
 
-This callback is invoked before a new group is added. The function should either manipulate the group and return it as an object of the same type (either `RuleGroupType` or `RuleGroupTypeIC`), or return `false` to cancel the addition of the group. You can use [`findPath`](./misc#findpath) to locate the parent group to which the new group will be added within the query hierarchy.
+This callback is invoked before a new group is added. The function should either manipulate the group and return it as an object of the same type (either `RuleGroupType` or `RuleGroupTypeIC`), or return `false` to cancel the addition of the group. You can use [`findPath`](./misc#findpath) to locate the parent group to which the new group will be added within the query hierarchy. The `context` parameter (fourth argument) can be passed from a custom [`addGroupAction`](#addgroupaction) component to its `onHandleClick` callback prop, which will in turn pass it to `onAddGroup`. This allows one to change the group that gets added (or avoid the action completely) based on arbitrary information.
 
 :::tip
 
@@ -766,11 +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
 
-`react-querybuilder` uses [`react-dnd`](https://react-dnd.github.io/react-dnd/) to enable drag-and-drop features. If your application already uses `react-dnd`, you should import and render `<QueryBuilderWithoutDndProvider />` instead of `<QueryBuilder />`. They are functionally the same, but the former will rely on your pre-existing `DndProvider` wrapper while the latter implements its own and will clash with a separate `DndProvider` higher up in the component tree (the error will typically look like this: "Cannot have two HTML5 backends at the same time.").
+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.
+
+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 />
+  </QueryBuilderDnD>
+);
+```
+
+:::tip
+
+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.")
 
 :::