feat: Added optional usageLimit property to field entity

- Added optional usageLimit property to field entity
- Updated API, Documentation and Demo sections on the library website
- Updated README

Author: Vojtěch Václav Porteš

README.md

@@ -100,6 +100,60 @@ export const MyBuilder = () => {
 };
 ```
 
+## Validation and Usage Limits
+
+Field metadata can define both value validation and structural usage limits.
+Use `validation` for rule-local checks like required values or numeric bounds,
+and use `usageLimit` when a field or shared field bucket should only appear a
+limited number of times globally or within the same parent group.
+
+```tsx
+const fields: IBuilderFieldProps[] = [
+  {
+    field: 'PRIMARY_EMAIL',
+    label: 'Primary email',
+    type: 'TEXT',
+    operators: ['EQUAL', 'CONTAINS'],
+    usageLimit: {
+      max: 1,
+      scope: 'global',
+    },
+    validation: {
+      required: true,
+    },
+  },
+  {
+    field: 'BILLING_CONTACT',
+    label: 'Billing contact',
+    type: 'TEXT',
+    operators: ['EQUAL'],
+    usageLimit: {
+      key: 'contact-field',
+      max: 1,
+      scope: 'parent',
+    },
+  },
+  {
+    field: 'SHIPPING_CONTACT',
+    label: 'Shipping contact',
+    type: 'TEXT',
+    operators: ['EQUAL'],
+    usageLimit: {
+      key: 'contact-field',
+      max: 1,
+      scope: 'parent',
+    },
+  },
+];
+```
+
+When a usage limit is exhausted, the field becomes disabled in the selector,
+and the built-in Add Rule action is disabled when no selectable fields remain
+in the current scope.
+
+- <a href="https://vojtechportes.github.io/react-query-builder/documentation/validation" target="_blank" rel="noopener noreferrer">Documentation: Validation</a>
+- <a href="https://vojtechportes.github.io/react-query-builder/api/fields" target="_blank" rel="noopener noreferrer">API: Fields</a>
+
 ## Dynamic Field Options
 
 When list options depend on other rules or on external application state, keep

example/src/constants/demo-data.ts

@@ -122,6 +122,26 @@ export const demoFields: IBuilderFieldProps[] = [
     type: 'STATEMENT',
     value: 'HAS_DEBT() AND LAST_PAYMENT_DAYS_AGO() > 30',
   },
+  {
+    field: 'FIRST_NAME',
+    label: 'First name',
+    type: 'TEXT',
+    operators: [
+      'EQUAL',
+      'NOT_EQUAL',
+      'CONTAINS',
+      'NOT_CONTAINS',
+      'STARTS_WITH',
+      'ENDS_WITH',
+    ],
+    validation: {
+      required: true,
+    },
+    usageLimit: {
+      max: 1,
+      scope: 'global'
+    }
+  },
 ];
 
 export const initialQueryTree: DenormalizedQuery = [

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

@@ -224,9 +224,19 @@ const fieldBaseSignature = `interface IBuilderFieldBase<TType, TValue, TValidati
   value?: TValue;
   type: TType;
   operators?: BuilderFieldOperator[];
+  usageLimit?: IBuilderFieldUsageLimit;
   validation?: TValidation;
 }`;
 
+const fieldUsageLimitSignature = `export type BuilderFieldUsageLimitScope = 'global' | 'parent';
+
+export interface IBuilderFieldUsageLimit {
+  key?: string;
+  max: number;
+  scope?: BuilderFieldUsageLimitScope;
+  message?: BuilderValidationMessage;
+}`;
+
 const fieldOptionTypesSignature = `export type BuilderFieldOption = {
   value: string | number;
   label: string;
@@ -1004,13 +1014,18 @@ export const apiPages: IApiPage[] = [
     sectionTitle: 'Core API',
     summary: '',
     description:
-      'Field definition API reference for IBuilderFieldProps, field types, operators, and validation metadata.',
+      'Field definition API reference for IBuilderFieldProps, field types, operators, usageLimit, and validation metadata.',
     searchText:
-      'IBuilderFieldProps field label type value operators validation BOOLEAN TEXT DATE NUMBER STATEMENT LIST MULTI_LIST GROUP BuilderFieldOption BuilderFieldOptionsStatus IBuilderFieldOptionState INearestFieldMatch IBuilderFieldChange dynamic field options',
+      'IBuilderFieldProps field label type value operators usageLimit validation BOOLEAN TEXT DATE NUMBER STATEMENT LIST MULTI_LIST GROUP BuilderFieldOption BuilderFieldOptionsStatus IBuilderFieldOptionState INearestFieldMatch IBuilderFieldChange dynamic field options',
     content: (
       <>
         <CodeBlock code={fieldTypesSignature} language="ts" label="Field unions" />
         <CodeBlock code={fieldBaseSignature} language="ts" label="Shared field shape" />
+        <CodeBlock
+          code={fieldUsageLimitSignature}
+          language="ts"
+          label="Field usage limits"
+        />
         <CodeBlock
           code={fieldOptionTypesSignature}
           language="ts"
@@ -1023,8 +1038,16 @@ export const apiPages: IApiPage[] = [
           <li><ItemTitle><InlineCode>type</InlineCode>:</ItemTitle> Required field type. This controls which widget and value semantics are used.</li>
           <li><ItemTitle><InlineCode>value</InlineCode>:</ItemTitle> Optional default or backing field value metadata. For <InlineCode>LIST</InlineCode> and <InlineCode>MULTI_LIST</InlineCode>, this is the initial static option set.</li>
           <li><ItemTitle><InlineCode>operators</InlineCode>:</ItemTitle> Optional operator whitelist. When omitted, the builder falls back to the default operators for the field type.</li>
+          <li><ItemTitle><InlineCode>usageLimit</InlineCode>:</ItemTitle> Optional structural constraint that limits how many rules may use this field or its shared usage bucket.</li>
           <li><ItemTitle><InlineCode>validation</InlineCode>:</ItemTitle> Optional validation config. The shape depends on field type.</li>
         </List>
+        <SectionTitle>usageLimit</SectionTitle>
+        <List>
+          <li><ItemTitle><InlineCode>max</InlineCode>:</ItemTitle> Required maximum number of matching rules allowed in the selected scope.</li>
+          <li><ItemTitle><InlineCode>scope</InlineCode>:</ItemTitle> Optional. Defaults to <InlineCode>global</InlineCode>. Use <InlineCode>parent</InlineCode> to limit usage only within the same immediate parent group.</li>
+          <li><ItemTitle><InlineCode>key</InlineCode>:</ItemTitle> Optional shared bucket identifier. When omitted, the builder uses the field&apos;s own <InlineCode>field</InlineCode> value.</li>
+          <li><ItemTitle><InlineCode>message</InlineCode>:</ItemTitle> Optional custom validation message used when persisted or imported data exceeds the allowed limit.</li>
+        </List>
         <SectionTitle>Type notes</SectionTitle>
         <List>
           <li><ItemTitle><InlineCode>BOOLEAN</InlineCode> / <InlineCode>TEXT</InlineCode> / <InlineCode>DATE</InlineCode> / <InlineCode>NUMBER</InlineCode>:</ItemTitle> The standard scalar field families with built-in widget and validation behavior.</li>
@@ -1034,6 +1057,7 @@ export const apiPages: IApiPage[] = [
         </List>
         <AlertBox title="Documentation" variant="info">
           <TextLink to="/documentation/usage">Usage</TextLink>,{' '}
+          <TextLink to="/documentation/validation">Validation</TextLink>,{' '}
           <TextLink to="/documentation/dynamic-field-options">
             Dynamic Field Options
           </TextLink>, and <TextLink to="/documentation/localization">Localization</TextLink>.

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

@@ -526,6 +526,48 @@ const validationSnippet = `const fields: IBuilderFieldProps[] = [
   onChange={setData}
 />;`;
 
+const usageLimitSnippet = `const fields: IBuilderFieldProps[] = [
+  {
+    field: 'PRIMARY_EMAIL',
+    label: 'Primary email',
+    type: 'TEXT',
+    operators: ['EQUAL', 'CONTAINS'],
+    usageLimit: {
+      max: 1,
+      scope: 'global',
+    },
+  },
+  {
+    field: 'BILLING_CONTACT',
+    label: 'Billing contact',
+    type: 'TEXT',
+    operators: ['EQUAL'],
+    usageLimit: {
+      key: 'contact-field',
+      max: 1,
+      scope: 'parent',
+    },
+  },
+  {
+    field: 'SHIPPING_CONTACT',
+    label: 'Shipping contact',
+    type: 'TEXT',
+    operators: ['EQUAL'],
+    usageLimit: {
+      key: 'contact-field',
+      max: 1,
+      scope: 'parent',
+    },
+  },
+];
+
+<Builder
+  fields={fields}
+  data={data}
+  showValidation
+  onChange={setData}
+/>;`;
+
 const builderBehaviorSnippet = `<Builder
   fields={fields}
   data={data}
@@ -1666,9 +1708,9 @@ export const documentationPages: IDocumentationPage[] = [
     sectionTitle: 'Getting Started',
     summary: '',
     description:
-      'Built-in validation for fields and rules, validation rendering with showValidation, and custom validator integration.',
+      'Built-in validation for fields and rules, structural usageLimit constraints, validation rendering with showValidation, and custom validator integration.',
     searchText:
-      'Validation built-in validation validator showValidation onStateChange required minLength maxLength minItems maxItems range validation rules fields builder',
+      'Validation built-in validation validator usageLimit showValidation onStateChange required minLength maxLength minItems maxItems range validation rules fields builder',
     content: (
       <>
         <p>
@@ -1689,10 +1731,26 @@ export const documentationPages: IDocumentationPage[] = [
           <li>List and multi-list fields support item-count constraints such as <InlineCode>minItems</InlineCode> and <InlineCode>maxItems</InlineCode>.</li>
           <li>Range operators such as <InlineCode>BETWEEN</InlineCode> can use <InlineCode>range</InlineCode> validation to validate both values together.</li>
         </List>
+        <SectionTitle>Structural usage limits</SectionTitle>
+        <p>
+          Use <InlineCode>usageLimit</InlineCode> when a constraint depends on how
+          many rules already use a field or a shared usage bucket. This is separate
+          from value validation because it governs query structure rather than the
+          validity of a single rule value.
+        </p>
+        <CodeBlock code={usageLimitSnippet} language="tsx" label="Field usage limits" />
+        <List>
+          <li><InlineCode>max</InlineCode> defines how many matching rules are allowed inside the selected scope.</li>
+          <li><InlineCode>scope=&quot;global&quot;</InlineCode> limits usage across the whole query tree.</li>
+          <li><InlineCode>scope=&quot;parent&quot;</InlineCode> limits usage only among sibling rules in the same immediate parent group.</li>
+          <li><InlineCode>key</InlineCode> lets multiple different fields share the same quota bucket.</li>
+          <li>Exhausted fields are disabled in the field selector, and the Add Rule button is disabled when no selectable fields remain in the current scope.</li>
+          <li><InlineCode>showValidation</InlineCode> still surfaces an issue when data arrives in an already invalid state, such as external input or text mode edits.</li>
+        </List>
         <AlertBox title="Custom validator" variant="info">
           Use <InlineCode>validator</InlineCode> when validation depends on
           multiple rules, external state, or rules that are not expressible in
-          field-level validation config.
+          field-level validation config or <InlineCode>usageLimit</InlineCode>.
         </AlertBox>
         <AlertBox title="API reference" variant="info">
           <TextLink to="/api/builder">Builder</TextLink> and{' '}

src/builder/builder.test.tsx

@@ -245,6 +245,28 @@ describe('#components/Builder', () => {
     expect(queryByDataTest(container, 'Redo')).toBeNull();
   });
 
+  it('Disables root add rule when all root-scope fields are exhausted', () => {
+    const limitedFields: IBuilderFieldProps[] = [
+      {
+        field: 'MOCK_FIELD',
+        label: 'Mock Field',
+        type: 'TEXT',
+        operators: ['EQUAL'],
+        usageLimit: { max: 1, scope: 'parent' },
+      },
+    ];
+    const { container } = render(
+      <Builder
+        fields={limitedFields}
+        data={[{ field: 'MOCK_FIELD', value: 'alpha', operator: 'EQUAL' }]}
+        singleRootGroup={false}
+        onChange={jest.fn()}
+      />
+    );
+
+    expect(getByDataTest(container, 'AddRootRule')).toBeDisabled();
+  });
+
   it('Switches the builder into SQL text mode', () => {
     const { container } = render(
       <Builder

src/builder/builder.tsx

@@ -62,6 +62,7 @@ import { isNodeDeletionProtected } from '../utils/is-node-deletion-protected.uti
 import { createBuilderFieldOptionsStore } from './utils/create-builder-field-options-store.util';
 import { getNearestFieldMatch } from './utils/get-nearest-field-match.util';
 import { isBuilderFieldInUse } from './utils/is-builder-field-in-use.util';
+import { canAddRuleForParent } from './utils/resolve-builder-field-usage.util';
 import { resolveBuilderFieldOptionState } from './utils/resolve-builder-field-option-state.util';
 import { resolveReconciledBuilderRuleValue } from './utils/resolve-reconciled-builder-rule-value.util';
 
@@ -142,6 +143,7 @@ export const Builder = forwardRef<IBuilderRef, IBuilderProps>(({
     fieldOptionsStoreRef.current = createBuilderFieldOptionsStore();
   }
   const filteredData = data.filter((item) => !item.parent);
+  const canAddRootRule = canAddRuleForParent(data, fields);
   const AddComponent = components.Add || Button;
   const AlertComponent = components.Alert || defaultComponents.Alert || DefaultAlert;
   const OutlinedButtonComponent =
@@ -845,6 +847,7 @@ export const Builder = forwardRef<IBuilderRef, IBuilderProps>(({
           onSwitchToBuilderMode={handleSwitchToBuilderMode}
           onSwitchToTextMode={handleSwitchToTextMode}
           onAddRootRule={handleAddRootRule}
+          disableAddRootRule={!canAddRootRule}
           onAddRootGroup={handleAddRootGroup}
           onAddRootGroupWithoutModifiers={handleAddRootGroupWithoutModifiers}
           AddComponent={AddComponent}

src/builder/components/builder-root-actions.tsx

@@ -23,6 +23,7 @@ export interface IBuilderRootActionsProps {
   onSwitchToBuilderMode?: () => void;
   onSwitchToTextMode?: () => void;
   onAddRootRule: () => void;
+  disableAddRootRule?: boolean;
   onAddRootGroup: () => void;
   onAddRootGroupWithoutModifiers: () => void;
   AddComponent: React.ComponentType<IButtonProps>;
@@ -49,6 +50,7 @@ export const BuilderRootActions: FC<IBuilderRootActionsProps> = ({
   onSwitchToBuilderMode,
   onSwitchToTextMode,
   onAddRootRule,
+  disableAddRootRule = false,
   onAddRootGroup,
   onAddRootGroupWithoutModifiers,
   AddComponent,
@@ -124,7 +126,11 @@ export const BuilderRootActions: FC<IBuilderRootActionsProps> = ({
       ) : null}
       {!readOnly && strings.group && !singleRootGroup ? (
         <>
-          <AddComponent onClick={onAddRootRule} data-test="AddRootRule">
+          <AddComponent
+            onClick={onAddRootRule}
+            disabled={disableAddRootRule}
+            data-test="AddRootRule"
+          >
             {strings.group.addRule}
           </AddComponent>
           {groupTypes === 'both' ? (

src/builder/index.ts

@@ -29,6 +29,7 @@ export type {
   BuilderFieldOptionsStatus,
   BuilderRuleValueReconciliationStrategy,
   BuilderFieldType,
+  BuilderFieldUsageLimitScope,
   BuilderFieldValue,
   BuilderGroupMode,
   BuilderNewNodePlacement,
@@ -47,6 +48,7 @@ export type {
   IBuilderFieldOptionState,
   IBuilderRuleValueReconciliationConfig,
   IBuilderFieldValidationBase,
+  IBuilderFieldUsageLimit,
   IBuilderOperatorValidationRule,
   IBuilderStateChange,
   IBuilderValidationConfig,

src/builder/types/index.ts

@@ -81,12 +81,22 @@ export type BuilderFieldValue =
   | boolean
   | Array<{ value: string | number; label: string }>;
 
+export type BuilderFieldUsageLimitScope = 'global' | 'parent';
+
+export interface IBuilderFieldUsageLimit {
+  key?: string;
+  max: number;
+  scope?: BuilderFieldUsageLimitScope;
+  message?: BuilderValidationMessage;
+}
+
 export interface IBuilderValidationMessageContext {
   field: IBuilderFieldProps;
   operator?: BuilderFieldOperator;
   value?: BuilderFieldValue;
   ruleId?: string;
   rangeBoundary?: 'start' | 'end';
+  usageLimit?: IBuilderFieldUsageLimit;
 }
 
 export type BuilderValidationMessage =
@@ -223,6 +233,7 @@ interface IBuilderFieldBase<
   type: TType;
   operators?: BuilderFieldOperator[];
   validation?: TValidation;
+  usageLimit?: IBuilderFieldUsageLimit;
 }
 
 export type IBooleanFieldProps = IBuilderFieldBase<