feat: Added newNodePlacement property allowing to place new node either to the start or to the end of parent node

Author: Vojtěch Václav Porteš

example/src/components/demo-playground.tsx

@@ -77,6 +77,37 @@ const Toggle = styled.input<{ $disabled?: boolean }>`
   }
 `;
 
+const SelectField = styled.label`
+  display: grid;
+  gap: 0.35rem;
+`;
+
+const SelectFieldLabel = styled.span`
+  font-size: 0.95rem;
+  font-weight: 400;
+  color: #334155;
+`;
+
+const SelectControl = styled.select`
+  width: 100%;
+  padding: 0.68rem 2.2rem 0.68rem 0.85rem;
+  border: 1px solid #dbe4f0;
+  border-radius: 10px;
+  background: #fff;
+  color: #0f172a;
+  font-size: 0.92rem;
+  appearance: none;
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 12 12' fill='none'%3E%3Cpath d='M2.5 4.5L6 8L9.5 4.5' stroke='%230f172a' stroke-width='1.5' stroke-linecap='round' stroke-linejoin='round'/%3E%3C/svg%3E");
+  background-repeat: no-repeat;
+  background-position: right 0.85rem center;
+
+  &:focus {
+    outline: none;
+    border-color: ${siteTheme.primaryLight};
+    box-shadow: 0 0 0 3px ${siteTheme.primaryGlow};
+  }
+`;
+
 const ChoiceGroup = styled.div`
   display: grid;
   gap: 0.7rem;
@@ -161,6 +192,9 @@ 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 [newNodePlacement, setNewNodePlacement] = React.useState<
+    'append' | 'prepend'
+  >('append');
   const [history, setHistory] = React.useState(false);
   const [textMode, setTextMode] = React.useState(false);
   const [defaultMode, setDefaultMode] = React.useState<'builder' | 'text'>('builder');
@@ -206,6 +240,7 @@ export const DemoPlayground: React.FC<IDemoPlaygroundProps> = ({
     cloneable,
     onChange: setData,
     draggable,
+    newNodePlacement,
     history,
     textMode,
     defaultMode,
@@ -230,6 +265,7 @@ export const DemoPlayground: React.FC<IDemoPlaygroundProps> = ({
         lockable,
         cloneable,
         draggable,
+        newNodePlacement,
         history,
         textMode,
         defaultMode,
@@ -245,6 +281,7 @@ export const DemoPlayground: React.FC<IDemoPlaygroundProps> = ({
       lockable,
       cloneable,
       draggable,
+      newNodePlacement,
       history,
       textMode,
       defaultMode,
@@ -368,6 +405,19 @@ export const DemoPlayground: React.FC<IDemoPlaygroundProps> = ({
             />
             <span>Show validation errors</span>
           </ToggleRow>
+
+          <SelectField>
+            <SelectFieldLabel>New node placement</SelectFieldLabel>
+            <SelectControl
+              value={newNodePlacement}
+              onChange={event =>
+                setNewNodePlacement(event.target.value as 'append' | 'prepend')
+              }
+            >
+              <option value="append">Append to end</option>
+              <option value="prepend">Prepend to start</option>
+            </SelectControl>
+          </SelectField>
         </Panel>
 
         <Panel>

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

@@ -22,6 +22,7 @@ const builderSignature = `export interface IBuilderProps {
   draggable?: boolean;
   singleRootGroup?: boolean;
   groupTypes?: 'with-modifiers' | 'without-modifiers' | 'both';
+  newNodePlacement?: 'append' | 'prepend';
   validator?: IBuilderValidator;
   onStateChange?: (state: IBuilderStateChange) => void;
   showValidation?: boolean;
@@ -481,7 +482,7 @@ export const apiPages: IApiPage[] = [
     description:
       'Builder component API reference for IBuilderProps, controlled data flow, validation, and editing options.',
     searchText:
-      'Builder component IBuilderProps onChange controlled component defaults strings components validator history state change undo redo canUndo canRedo',
+      'Builder component IBuilderProps onChange controlled component defaults strings components validator history state change undo redo canUndo canRedo newNodePlacement append prepend',
     content: (
       <>
         <CodeBlock code={builderSignature} language="ts" label="IBuilderProps" />
@@ -501,6 +502,7 @@ export const apiPages: IApiPage[] = [
           <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>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>
           <li><ItemTitle><InlineCode>validator</InlineCode>:</ItemTitle> Optional function that receives the denormalized query plus validation context and returns a validation result synchronously or asynchronously.</li>
           <li><ItemTitle><InlineCode>onStateChange</InlineCode>:</ItemTitle> Optional callback fired with <InlineCode>data</InlineCode>, <InlineCode>isValid</InlineCode>, the full validation object, and history state flags such as <InlineCode>canUndo</InlineCode> and <InlineCode>canRedo</InlineCode>.</li>
           <li><ItemTitle><InlineCode>showValidation</InlineCode>:</ItemTitle> Defaults to <InlineCode>false</InlineCode>. Controls whether validation issues are rendered in the built-in UI.</li>

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

@@ -309,6 +309,7 @@ const builderBehaviorSnippet = `<Builder
   lockable
   cloneable
   draggable
+  newNodePlacement="prepend"
   singleRootGroup={false}
   groupTypes="both"
   onChange={setData}
@@ -325,6 +326,10 @@ const builderBehaviorSnippet = `<Builder
 // draggable:
 // Enables drag-and-drop for editable rules and groups.
 //
+// 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".
+//
 // singleRootGroup={false}:
 // Allows multiple root-level nodes instead of wrapping everything into one root group.
 //
@@ -1047,9 +1052,9 @@ export const documentationPages: IDocumentationPage[] = [
     sectionTitle: 'Getting Started',
     summary: '',
     description:
-      'Documentation for clone controls, drag-and-drop, root-group behavior, and group mode configuration.',
+      '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 singleRootGroup groupTypes with modifiers without modifiers both root group',
+      'builder behavior cloneable clone controls draggable drag and drop newNodePlacement append prepend singleRootGroup groupTypes with modifiers without modifiers both root group',
     content: (
       <>
         <p>
@@ -1089,6 +1094,26 @@ export const documentationPages: IDocumentationPage[] = [
             wants multiple top-level nodes instead of one wrapped root group.
           </li>
         </List>
+        <SectionTitle>newNodePlacement</SectionTitle>
+        <List>
+          <li>
+            Defaults to <InlineCode>'append'</InlineCode>, which inserts newly
+            added rules and groups at the end of their parent.
+          </li>
+          <li>
+            Set it to <InlineCode>'prepend'</InlineCode> to insert new rules
+            and groups at the beginning of their parent instead.
+          </li>
+          <li>
+            This affects built-in Add Rule and Add Group controls, root-level
+            add controls, and imperative ref methods when no explicit index is
+            provided.
+          </li>
+          <li>
+            It does not change cloning or drag-and-drop behavior, since those
+            actions already use explicit target positions.
+          </li>
+        </List>
         <SectionTitle>groupTypes</SectionTitle>
         <List>
           <li>

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

@@ -8,6 +8,7 @@ export const formatBuilderSource = ({
   lockable,
   cloneable,
   draggable,
+  newNodePlacement,
   history,
   textMode,
   defaultMode,
@@ -59,6 +60,9 @@ export const formatBuilderSource = ({
     lockable ? 'lockable' : null,
     cloneable ? 'cloneable' : null,
     draggable ? 'draggable' : null,
+    newNodePlacement === 'prepend'
+      ? 'newNodePlacement="prepend"'
+      : null,
     history ? 'history' : null,
     textMode ? 'textMode' : null,
     textMode && defaultMode === 'text' ? 'defaultMode="text"' : null,

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

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

src/builder-context.tsx

@@ -1,6 +1,7 @@
 import React, { FC, createContext } from 'react';
 import {
   BuilderGroupMode,
+  BuilderNewNodePlacement,
   IBuilderComponentsProps,
   IBuilderFieldProps,
   IBuilderValidationResult,
@@ -22,6 +23,7 @@ export interface IBuilderContextProps {
   draggable?: boolean;
   singleRootGroup?: boolean;
   groupTypes?: BuilderGroupMode;
+  newNodePlacement?: BuilderNewNodePlacement;
   showValidation?: boolean;
   validation?: IBuilderValidationResult;
   components: IBuilderComponentsProps;
@@ -53,6 +55,7 @@ export interface IBuilderContextProviderProps {
   draggable?: boolean;
   singleRootGroup?: boolean;
   groupTypes?: BuilderGroupMode;
+  newNodePlacement?: BuilderNewNodePlacement;
   showValidation?: boolean;
   validation?: IBuilderValidationResult;
   components: IBuilderComponentsProps;
@@ -78,6 +81,7 @@ export const BuilderContextProvider: FC<IBuilderContextProviderProps> = ({
   draggable,
   singleRootGroup,
   groupTypes,
+  newNodePlacement,
   showValidation,
   validation,
   setData,
@@ -139,6 +143,7 @@ export const BuilderContextProvider: FC<IBuilderContextProviderProps> = ({
         draggable,
         singleRootGroup,
         groupTypes,
+        newNodePlacement,
         showValidation,
         validation,
         setData,

src/builder/builder.test.tsx

@@ -1054,6 +1054,39 @@ describe('#components/Builder', () => {
     expect(getByDataTest(container, 'Redo')).toBeDisabled();
   });
 
+  it('Prepends new root nodes when newNodePlacement is set to prepend', () => {
+    const onChange = jest.fn();
+    const { container } = render(
+      <Builder
+        fields={fields}
+        data={[
+          { field: 'MOCK_FIELD', value: 'alpha', operator: 'EQUAL' },
+          { field: 'MOCK_NUMBER', value: 5, operator: 'NOT_EQUAL' },
+        ]}
+        singleRootGroup={false}
+        newNodePlacement="prepend"
+        onChange={onChange}
+      />
+    );
+
+    fireEvent.click(getByDataTest(container, 'AddRootRule'));
+
+    expect(onChange).toHaveBeenLastCalledWith([
+      expect.objectContaining({ field: '' }),
+      expect.objectContaining({ field: 'MOCK_FIELD', value: 'alpha' }),
+      expect.objectContaining({ field: 'MOCK_NUMBER', value: 5 }),
+    ]);
+
+    fireEvent.click(getByDataTest(container, 'AddRootGroup'));
+
+    expect(onChange).toHaveBeenLastCalledWith([
+      expect.objectContaining({ type: 'GROUP' }),
+      expect.objectContaining({ field: '' }),
+      expect.objectContaining({ field: 'MOCK_FIELD', value: 'alpha' }),
+      expect.objectContaining({ field: 'MOCK_NUMBER', value: 5 }),
+    ]);
+  });
+
   it('Undoes and redoes rule value edits when history is enabled', () => {
     const onChange = jest.fn();
     const { container } = render(
@@ -2236,4 +2269,67 @@ describe('#components/Builder', () => {
       },
     ]);
   });
+
+  it('Uses newNodePlacement for imperative add methods when index is omitted', () => {
+    const onChange = jest.fn();
+    let builderRefObject: React.MutableRefObject<IBuilderRef | null> | null = null;
+
+    const TestComponent = () => {
+      const builderRef = useBuilderRef();
+      builderRefObject = builderRef;
+
+      return (
+        <Builder
+          ref={builderRef}
+          fields={fields}
+          data={[
+            {
+              type: 'GROUP',
+              value: 'AND',
+              isNegated: false,
+              children: [
+                { field: 'MOCK_FIELD', value: 'alpha', operator: 'EQUAL' },
+                { field: 'MOCK_NUMBER', value: 5, operator: 'NOT_EQUAL' },
+              ],
+            },
+          ]}
+          newNodePlacement="prepend"
+          onChange={onChange}
+        />
+      );
+    };
+
+    render(<TestComponent />);
+
+    const getBuilderRef = () => {
+      const currentBuilderRef = builderRefObject?.current;
+      expect(currentBuilderRef).toBeDefined();
+      return currentBuilderRef as IBuilderRef;
+    };
+    const rootGroupId = getBuilderRef()
+      .getNodes()
+      .find((node) => 'type' in node)?.id as string;
+
+    act(() => {
+      expect(
+        getBuilderRef().addRule(
+          { field: 'MOCK_FIELD', value: 'beta', operator: 'EQUAL' },
+          rootGroupId
+        )
+      ).toBe(true);
+    });
+
+    expect(onChange).toHaveBeenLastCalledWith([
+      {
+        type: 'GROUP',
+        value: 'AND',
+        isNegated: false,
+        children: [
+          { field: 'MOCK_FIELD', value: 'beta', operator: 'EQUAL' },
+          { field: 'MOCK_FIELD', value: 'alpha', operator: 'EQUAL' },
+          { field: 'MOCK_NUMBER', value: 5, operator: 'NOT_EQUAL' },
+        ],
+      },
+    ]);
+  });
 });