@react-querybuilder/antd 7.8.0-alpha.0 → 8.0.0

package/README.md

@@ -1,10 +1,12 @@
 ## @react-querybuilder/antd
 
-Official [react-querybuilder](https://npmjs.com/package/react-querybuilder) components for [Ant Design](https://ant.design/).
+Official [react-querybuilder](https://npmjs.com/package/react-querybuilder) compatibility package for [Ant Design](https://ant.design/).
 
-To see them in action, check out the [`react-querybuilder` demo](https://react-querybuilder.js.org/demo/antd) or [load the example in CodeSandbox](https://githubbox.com/react-querybuilder/react-querybuilder/tree/main/examples/antd).
+- [Demo](https://react-querybuilder.js.org/demo/antd)
+- [Full documentation](https://react-querybuilder.js.org/)
+- [CodeSandbox](https://react-querybuilder.js.org/sandbox?t=antd) / [StackBlitz](https://react-querybuilder.js.org/sandbox?p=stackblitz&t=antd) example projects
 
-**[Full documentation](https://react-querybuilder.js.org/)**
+![Screenshot](../../_assets/screenshot-antd.png)
 
 ## Installation
 
@@ -15,36 +17,56 @@ npm i react-querybuilder @react-querybuilder/antd @ant-design/icons antd
 
 ## Usage
 
-To render Ant Design-compatible components in the query builder, wrap the `<QueryBuilder />` element in `<QueryBuilderAntD />`.
+To configure the query builder to use Ant Design-compatible components, place `QueryBuilderAntD` above `QueryBuilder` in the component hierarchy.
 
 ```tsx
 import { QueryBuilderAntD } from '@react-querybuilder/antd';
-import { QueryBuilder, RuleGroupType } from 'react-querybuilder';
+import { useState } from 'react';
+import { type Field, QueryBuilder, type RuleGroupType } from 'react-querybuilder';
 
-const fields = [
+const fields: Field[] = [
   { name: 'firstName', label: 'First Name' },
   { name: 'lastName', label: 'Last Name' },
 ];
 
-const App = () => {
+export function App() {
   const [query, setQuery] = useState<RuleGroupType>({ combinator: 'and', rules: [] });
 
   return (
     <QueryBuilderAntD>
-      <QueryBuilder fields={fields} query={query} onQueryChange={setQuery} />
+      <QueryBuilder fields={fields} defaultQuery={query} onQueryChange={setQuery} />
     </QueryBuilderAntD>
   );
-};
+}
 ```
 
-## Notes
+> [!NOTE]
+>
+> You may also want to reduce the width of the value editor component (which is 100% by default) with the following CSS rule.
+>
+> ```css
+> .queryBuilder .ant-input {
+>   width: auto;
+> }
+> ```
 
-- You may also want to reduce the width of the value editor component (100% by default) with the following CSS rule:
+`QueryBuilderAntD` is a React context provider that assigns the following props to all descendant `QueryBuilder` elements. The props can be overridden on the `QueryBuilder` or used directly without the context provider.
 
-  ```css
-  .queryBuilder .ant-input {
-    width: auto;
-  }
-  ```
+| Export                | `QueryBuilder` prop             |
+| --------------------- | ------------------------------- |
+| `antdControlElements` | `controlElements`               |
+| `antdTranslations`    | `translations`                  |
+| `AntDActionElement`   | `controlElements.actionElement` |
+| `AntDDragHandle`      | `controlElements.dragHandle`    |
+| `AntDNotToggle`       | `controlElements.notToggle`     |
+| `AntDShiftActions`    | `controlElements.shiftActions`  |
+| `AntDValueEditor`     | `controlElements.valueEditor`   |
+| `AntDValueSelector`   | `controlElements.valueSelector` |
 
-- This package exports `antdControlElements` which can be assigned directly to the `controlElements` prop on `<QueryBuilder />` (and also exports each component individually), but wrapping `<QueryBuilder />` in `<QueryBuilderAntD />` is the recommended method.
+> [!TIP]
+>
+> By default, this package uses icons from `@ant-design/icons` for button labels. To reset button labels to their default strings, use `defaultTranslations` from `react-querybuilder`.
+>
+> ```tsx
+> <QueryBuilderAntD translations={defaultTranslations}>
+> ```