feat: Added a possibility to disable negated groups by not rendering a "NOT" toggle and adjusting text mode validation

- Added allowGroupNegation property on Builder, defaults to true
- Updated text mode validation
- Updated library website and readme

Author: Vojtěch Václav Porteš

.codex/AGENTS.md

@@ -0,0 +1,7 @@
+Long-running tooling (tests, docker compose, migrations, etc.) must always be invoked with sensible timeouts or in non-interactive batch mode. Never leave a shell command waiting indefinitely—prefer explicit timeouts, scripted runs, or log polling after the command exits.
+
+Prefer arrow functions over function statements. Make sure each file contains exactly one function, one react component or set of constants that are related.
+
+If pattern is react component, function is tied to one or two interfaces or one or two styled components, they can be in one file. Once the file becomes too complex, prefer splitting types into ./types folder relative to the component or move styled components to ./components folder relative to the component.
+
+Utility functions should be always suffixed with .util.(ts|tsx).

.gitignore

@@ -9,6 +9,7 @@ node_modules
 .rts2_cache_umd
 *.tsbuildinfo
 dist
+.tmp
 
 /coverage
 example/dist

README.md

@@ -380,6 +380,9 @@ For advanced text editing, the package also exposes
 `@vojtechportes/react-query-builder/monaco`. The built-in editor is lightweight
 and works without extra dependencies, while the Monaco integration is the
 recommended path when locked query segments must stay protected in text mode.
+Set `allowGroupNegation={false}` to remove the group-level `NOT` toggle and
+reject `NOT (...)` groups in text mode, while still allowing operator-level
+negation such as `NOT IN` or `IS NOT NULL`.
 
 - <a href="https://vojtechportes.github.io/react-query-builder/documentation/text-mode" target="_blank" rel="noopener noreferrer">Documentation: Text Mode</a>
 - <a href="https://vojtechportes.github.io/react-query-builder/api/builder" target="_blank" rel="noopener noreferrer">API: Builder</a>

example/src/components/demo-playground.tsx

@@ -264,6 +264,7 @@ export const DemoPlayground: React.FC<IDemoPlaygroundProps> = ({
   const [lockable, setLockable] = React.useState(false);
   const [cloneable, setCloneable] = React.useState(false);
   const [draggable, setDraggable] = React.useState(false);
+  const [allowGroupNegation, setAllowGroupNegation] = React.useState(true);
   const [newNodePlacement, setNewNodePlacement] = React.useState<
     'append' | 'prepend'
   >('append');
@@ -332,6 +333,7 @@ export const DemoPlayground: React.FC<IDemoPlaygroundProps> = ({
     cloneable,
     onChange: setData,
     draggable,
+    allowGroupNegation,
     newNodePlacement,
     history,
     textMode,
@@ -358,6 +360,7 @@ export const DemoPlayground: React.FC<IDemoPlaygroundProps> = ({
         lockable,
         cloneable,
         draggable,
+        allowGroupNegation,
         newNodePlacement,
         history,
         textMode,
@@ -375,6 +378,7 @@ export const DemoPlayground: React.FC<IDemoPlaygroundProps> = ({
       lockable,
       cloneable,
       draggable,
+      allowGroupNegation,
       newNodePlacement,
       history,
       textMode,
@@ -440,6 +444,15 @@ export const DemoPlayground: React.FC<IDemoPlaygroundProps> = ({
             <span>Draggable nodes</span>
           </ToggleRow>
 
+          <ToggleRow>
+            <Toggle
+              type="checkbox"
+              checked={allowGroupNegation}
+              onChange={event => setAllowGroupNegation(event.target.checked)}
+            />
+            <span>Allow group negation</span>
+          </ToggleRow>
+
           <ToggleRow>
             <Toggle
               type="checkbox"

example/src/pages/api-page/pages/api-content.tsx

@@ -21,6 +21,7 @@ const builderSignature = `export interface IBuilderProps {
   lockable?: boolean;
   cloneable?: boolean;
   draggable?: boolean;
+  allowGroupNegation?: boolean;
   singleRootGroup?: boolean;
   groupTypes?: 'with-modifiers' | 'without-modifiers' | 'both';
   newNodePlacement?: 'append' | 'prepend';
@@ -866,6 +867,7 @@ export const apiPages: IApiPage[] = [
           <li><ItemTitle><InlineCode>lockable</InlineCode>:</ItemTitle> Defaults to <InlineCode>false</InlineCode>. Renders lock controls for rules and groups and writes the resulting lock state back into emitted query data without discarding existing targeted <InlineCode>readOnly.targets</InlineCode> configurations.</li>
           <li><ItemTitle><InlineCode>cloneable</InlineCode>:</ItemTitle> Defaults to <InlineCode>false</InlineCode>. Renders clone controls for rules and groups and inserts the cloned node directly below the original.</li>
           <li><ItemTitle><InlineCode>draggable</InlineCode>:</ItemTitle> Defaults to <InlineCode>false</InlineCode>. Enables drag-and-drop reordering and movement of query nodes.</li>
+          <li><ItemTitle><InlineCode>allowGroupNegation</InlineCode>:</ItemTitle> Defaults to <InlineCode>true</InlineCode>. When set to <InlineCode>false</InlineCode>, group negation is disabled across the builder: the group-level <InlineCode>NOT</InlineCode> control is hidden, emitted groups are normalized to non-negated form, and SQL text mode rejects group-level <InlineCode>NOT (...)</InlineCode> expressions. Operator-level negation such as <InlineCode>NOT IN</InlineCode>, <InlineCode>NOT LIKE</InlineCode>, <InlineCode>IS NOT NULL</InlineCode>, and <InlineCode>NOT BETWEEN</InlineCode> remains supported.</li>
           <li><ItemTitle><InlineCode>singleRootGroup</InlineCode>:</ItemTitle> Defaults to <InlineCode>true</InlineCode>. Wraps root-level items into a single root group and prevents deleting that root group. Text mode requires this to stay enabled.</li>
           <li><ItemTitle><InlineCode>groupTypes</InlineCode>:</ItemTitle> Defaults to <InlineCode>'with-modifiers'</InlineCode>. Controls whether groups use combinator/negation controls, modifierless groups, or both. When text mode is active, builder-compatible SQL round-tripping uses groups with modifiers.</li>
           <li><ItemTitle><InlineCode>newNodePlacement</InlineCode>:</ItemTitle> Defaults to <InlineCode>'append'</InlineCode>. Controls whether newly added rules and groups are inserted at the end or the beginning of their parent when built-in add actions or imperative add methods omit an explicit index.</li>

example/src/pages/documentation-page/pages/documentation-content.tsx

@@ -575,6 +575,7 @@ const builderBehaviorSnippet = `<Builder
   readOnlyProtectsDelete
   cloneable
   draggable
+  allowGroupNegation={false}
   newNodePlacement="prepend"
   singleRootGroup={false}
   groupTypes="both"
@@ -596,6 +597,10 @@ const builderBehaviorSnippet = `<Builder
 // draggable:
 // Enables drag-and-drop for editable rules and groups.
 //
+// allowGroupNegation={false}:
+// Hides the group-level NOT toggle and rejects NOT (...) groups in text mode
+// while still allowing operator-level negation such as NOT IN or IS NOT NULL.
+//
 // newNodePlacement="prepend":
 // Inserts newly added rules and groups at the beginning of their parent instead
 // of appending them to the end. The default is "append".
@@ -1833,7 +1838,7 @@ export const documentationPages: IDocumentationPage[] = [
     description:
       'Documentation for clone controls, drag-and-drop, insertion placement, root-group behavior, and group mode configuration.',
     searchText:
-      'builder behavior cloneable clone controls draggable drag and drop readOnlyProtectsDelete newNodePlacement append prepend singleRootGroup groupTypes with modifiers without modifiers both root group',
+      'builder behavior cloneable clone controls draggable drag and drop allowGroupNegation group negation not groups readOnlyProtectsDelete newNodePlacement append prepend singleRootGroup groupTypes with modifiers without modifiers both root group',
     content: (
       <>
         <p>
@@ -1914,6 +1919,30 @@ export const documentationPages: IDocumentationPage[] = [
             insert when adding a new group.
           </li>
         </List>
+        <SectionTitle>allowGroupNegation</SectionTitle>
+        <List>
+          <li>
+            Set <InlineCode>allowGroupNegation={false}</InlineCode> when you want
+            groups to keep combinators like <InlineCode>AND</InlineCode> and{' '}
+            <InlineCode>OR</InlineCode> but remove the group-level{' '}
+            <InlineCode>NOT</InlineCode> option.
+          </li>
+          <li>
+            This is narrower than <InlineCode>groupTypes</InlineCode>: it only
+            disables negating whole groups and does not affect whether groups
+            render combinator controls.
+          </li>
+          <li>
+            Operator-level negation still works normally, including{' '}
+            <InlineCode>NOT IN</InlineCode>, <InlineCode>NOT LIKE</InlineCode>,{' '}
+            <InlineCode>IS NOT NULL</InlineCode>, and{' '}
+            <InlineCode>NOT BETWEEN</InlineCode>.
+          </li>
+          <li>
+            When disabled, incoming negated groups are normalized to non-negated
+            form so the builder output stays consistent with the visible UI.
+          </li>
+        </List>
         <AlertBox title="Related docs" variant="info">
           <TextLink to="/documentation/history">Undo and Redo</TextLink>,{' '}
           <TextLink to="/documentation/builder-ref">Builder Ref</TextLink>,{' '}
@@ -2264,6 +2293,14 @@ export const documentationPages: IDocumentationPage[] = [
             operator, and value segments can be protected inline, while read-only
             negation is additionally enforced semantically and reported below the editor when changed.
           </li>
+          <li>
+            <ItemTitle>Group negation validation:</ItemTitle> When{' '}
+            <InlineCode>allowGroupNegation={false}</InlineCode>, the text editor
+            rejects group-level <InlineCode>NOT (...)</InlineCode> expressions
+            and highlights the offending <InlineCode>NOT</InlineCode> token, while
+            still allowing operator-level negation such as{' '}
+            <InlineCode>NOT IN</InlineCode> or <InlineCode>IS NOT NULL</InlineCode>.
+          </li>
           <li>
             <ItemTitle>Monaco packaging:</ItemTitle>{' '}
             <InlineCode>monaco-editor</InlineCode> is an optional peer dependency.

example/src/utils/builder-source/format-builder-source.ts

@@ -15,6 +15,7 @@ export const formatBuilderSource = ({
   lockable,
   cloneable,
   draggable,
+  allowGroupNegation,
   newNodePlacement,
   history,
   textMode,
@@ -91,6 +92,7 @@ import { components as radixComponents } from '@vojtechportes/react-query-builde
     lockable ? 'lockable' : null,
     cloneable ? 'cloneable' : null,
     draggable ? 'draggable' : null,
+    allowGroupNegation ? null : 'allowGroupNegation={false}',
     newNodePlacement === 'prepend'
       ? 'newNodePlacement="prepend"'
       : null,

example/src/utils/builder-source/types/index.ts

@@ -15,6 +15,7 @@ export interface IBuilderSourceOptions {
   lockable: boolean;
   cloneable: boolean;
   draggable: boolean;
+  allowGroupNegation: boolean;
   newNodePlacement: 'append' | 'prepend';
   history: boolean;
   textMode: boolean;

src/builder-context.tsx

@@ -24,6 +24,7 @@ export interface IBuilderContextProps {
   lockable?: boolean;
   cloneable?: boolean;
   draggable?: boolean;
+  allowGroupNegation?: boolean;
   singleRootGroup?: boolean;
   groupTypes?: BuilderGroupMode;
   newNodePlacement?: BuilderNewNodePlacement;
@@ -61,6 +62,7 @@ export interface IBuilderContextProviderProps {
   lockable?: boolean;
   cloneable?: boolean;
   draggable?: boolean;
+  allowGroupNegation?: boolean;
   singleRootGroup?: boolean;
   groupTypes?: BuilderGroupMode;
   newNodePlacement?: BuilderNewNodePlacement;
@@ -96,6 +98,7 @@ export const BuilderContextProvider: FC<IBuilderContextProviderProps> = ({
   lockable,
   cloneable,
   draggable,
+  allowGroupNegation,
   singleRootGroup,
   groupTypes,
   newNodePlacement,
@@ -163,6 +166,7 @@ export const BuilderContextProvider: FC<IBuilderContextProviderProps> = ({
         lockable,
         cloneable,
         draggable,
+        allowGroupNegation,
         singleRootGroup,
         groupTypes,
         newNodePlacement,

src/builder/builder.test.tsx

@@ -832,6 +832,29 @@ describe('#components/Builder', () => {
     ).toContain('Negation is read-only');
   });
 
+  it('Rejects negation in text mode when allowGroupNegation is false', () => {
+    const onChange = jest.fn();
+    const { container } = render(
+      <Builder
+        fields={fields}
+        data={[{ field: 'MOCK_FIELD', value: 'alpha', operator: 'EQUAL' }]}
+        textMode
+        defaultMode="text"
+        allowGroupNegation={false}
+        onChange={onChange}
+      />
+    );
+
+    fireEvent.change(getByDataTest(container, 'TextModeEditor'), {
+      target: { value: "NOT (MOCK_FIELD = 'alpha')" },
+    });
+
+    expect(onChange).not.toHaveBeenCalled();
+    expect(getByDataTest(container, 'TextModeError').textContent).toContain(
+      'Negation is not allowed'
+    );
+  });
+
   it('Preserves protected ranges after editing an unlocked value in text mode', async () => {
     const onChange = jest.fn();
     const { container } = render(
@@ -2312,6 +2335,82 @@ describe('#components/Builder', () => {
     expect(queryByDataTest(container, 'Option[or]')).toBeNull();
   });
 
+  it('Hides the negation control when allowGroupNegation is false', () => {
+    const { container } = render(
+      <Builder
+        fields={fields}
+        data={[
+          {
+            type: 'GROUP',
+            value: 'AND',
+            isNegated: false,
+            children: [{ field: 'MOCK_FIELD', value: '', operator: 'EQUAL' }],
+          },
+        ]}
+        allowGroupNegation={false}
+        onChange={jest.fn()}
+      />
+    );
+
+    expect(queryByDataTest(container, 'Option[not]')).toBeNull();
+  });
+
+  it('Removes negation from emitted group data when allowGroupNegation is false', () => {
+    const { container } = render(
+      <Builder
+        fields={fields}
+        data={[
+          {
+            type: 'GROUP',
+            value: 'AND',
+            isNegated: true,
+            children: [{ field: 'MOCK_FIELD', value: 'alpha', operator: 'EQUAL' }],
+          },
+        ]}
+        textMode
+        defaultMode="text"
+        allowGroupNegation={false}
+        onChange={jest.fn()}
+      />
+    );
+
+    expect(
+      (getByDataTest(container, 'TextModeEditor') as HTMLTextAreaElement).value
+    ).toBe("(MOCK_FIELD = 'alpha')");
+  });
+
+  it('Stays stable when rerendered with negated incoming data and allowGroupNegation is false', async () => {
+    const onStateChange = jest.fn();
+    const props: IBuilderProps = {
+      fields,
+      data: [
+        {
+          type: 'GROUP',
+          value: 'AND',
+          isNegated: true,
+          children: [{ field: 'MOCK_FIELD', value: 'alpha', operator: 'EQUAL' }],
+        },
+      ],
+      allowGroupNegation: false,
+      onStateChange,
+      onChange: jest.fn(),
+    };
+    const { rerender } = render(<Builder {...props} />);
+
+    await waitFor(() =>
+      expect(onStateChange.mock.calls.length).toBeGreaterThanOrEqual(1)
+    );
+    const initialCallCount = onStateChange.mock.calls.length;
+
+    rerender(<Builder {...props} />);
+
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 50));
+    });
+
+    expect(onStateChange).toHaveBeenCalledTimes(initialCallCount);
+  });
+
   it('Locks the builder to a single undeletable root group', () => {
     const { container } = render(
       <Builder