feat: Added dynamic field and rule option APIs

- Added imperative APIs for dynamic field-level and rule-level options
- Added dependency-aware rule option binding, nearest-field lookup, and rule dependency subscriptions
- Added explicit rule value reconciliation for strict select semantics
- Support numeric option values across the imperative option APIs
- Updated the documentation, API reference, live examples, and README
- Added regression tests for hydration, reloads, dependencies, and reconciliation edge cases

Author: Vojtěch Václav Porteš

README.md

@@ -109,7 +109,8 @@ API instead of replacing the full field definition.
 This is especially useful for dependent selects, async option loading, and
 integrations with tools like TanStack React Query.
 
-The imperative API includes methods such as:
+Use field-level methods when every rule of the same field should share one
+runtime option set:
 
 - `isFieldInUse(field)`
 - `setFieldOptions(field, options)`
@@ -118,6 +119,16 @@ The imperative API includes methods such as:
 - `reloadFieldOptions(field)`
 - `clearFieldOptions(field)`
 
+Use rule-level methods when options depend on other rules or on surrounding app
+state:
+
+- `bindRuleOptions(field, config)`
+- `useBuilderRuleDependencies(builderRef, field, dependencyFields)`
+- `subscribeToRuleDependencies(field, dependencyFields, listener)`
+- `setRuleOptions(ruleId, options)`
+- `setRuleOptionsStatus(ruleId, status)`
+- `reconcileRuleValueWithOptions(ruleId, { strategy: 'clear-if-missing' })`
+
 See the Dynamic Field Options documentation for the full concept, live example,
 and React Query integration example:
 

example/src/components/imperative-field-options-demo.tsx

@@ -6,6 +6,7 @@ import {
   type DenormalizedQuery,
   type IBuilderFieldProps,
 } from '@vojtechportes/react-query-builder';
+import { waitForTimeout } from './utils/wait-for-timeout.util';
 
 const DemoCard = styled.div`
   display: grid;
@@ -16,36 +17,6 @@ const DemoCard = styled.div`
   background: linear-gradient(180deg, #ffffff 0%, #f8fbff 100%);
 `;
 
-const Toolbar = styled.div`
-  display: flex;
-  flex-wrap: wrap;
-  gap: 0.75rem;
-  align-items: center;
-  justify-content: space-between;
-`;
-
-const StatusRow = styled.div`
-  display: flex;
-  flex-wrap: wrap;
-  gap: 0.75rem;
-  font-size: 0.92rem;
-  color: #475569;
-`;
-
-const SmallButton = styled.button`
-  padding: 0.6rem 0.9rem;
-  border: 1px solid #cbd5e1;
-  border-radius: 999px;
-  background: #fff;
-  color: #0f172a;
-  cursor: pointer;
-
-  &:hover {
-    border-color: #93c5fd;
-    background: #eff6ff;
-  }
-`;
-
 const fields: IBuilderFieldProps[] = [
   {
     field: 'COUNTRY',
@@ -74,153 +45,88 @@ const initialData: DenormalizedQuery = [
     isNegated: false,
     children: [
       {
-        field: 'COUNTRY',
-        operator: 'EQUAL',
-        value: 'CZ',
+        type: 'GROUP',
+        value: 'AND',
+        isNegated: false,
+        children: [
+          {
+            field: 'COUNTRY',
+            operator: 'EQUAL',
+            value: 'CZ',
+          },
+          {
+            field: 'CITY',
+            operator: 'EQUAL',
+            value: 'PRG',
+          },
+        ],
       },
       {
-        field: 'CITY',
-        operator: 'EQUAL',
-        value: '',
+        type: 'GROUP',
+        value: 'AND',
+        isNegated: false,
+        children: [
+          {
+            field: 'COUNTRY',
+            operator: 'EQUAL',
+            value: 'SK',
+          },
+          {
+            field: 'CITY',
+            operator: 'EQUAL',
+            value: 'BTS',
+          },
+        ],
       },
     ],
   },
 ];
 
+const cityOptionsByCountry = {
+  CZ: [
+    { value: 'PRG', label: 'Prague' },
+    { value: 'BRN', label: 'Brno' },
+    { value: 'OSR', label: 'Ostrava' },
+  ],
+  SK: [
+    { value: 'BTS', label: 'Bratislava' },
+    { value: 'KSC', label: 'Kosice' },
+    { value: 'ZIL', label: 'Zilina' },
+  ],
+  DE: [
+    { value: 'BER', label: 'Berlin' },
+    { value: 'MUC', label: 'Munich' },
+    { value: 'HAM', label: 'Hamburg' },
+  ],
+} as const;
+
 export const ImperativeFieldOptionsDemo: React.FC = () => {
   const [data, setData] = React.useState<DenormalizedQuery>(initialData);
-  const [cityOptionsStatus, setCityOptionsStatus] = React.useState<
-    'idle' | 'loading' | 'success' | 'error'
-  >('idle');
-  const [cityReloadToken, setCityReloadToken] = React.useState(0);
   const builderRef = useBuilderRef();
-  const cityRuleInUse = React.useMemo(
-    () =>
-      data.some(
-        node =>
-          'children' in node &&
-          node.children.some(
-            child => 'field' in child && child.field === 'CITY'
-          )
-      ),
-    [data]
-  );
-  const selectedCountry = React.useMemo(() => {
-    const rootGroup = data[0];
-    const countryRule =
-      rootGroup && 'children' in rootGroup
-        ? rootGroup.children.find(
-            child => 'field' in child && child.field === 'COUNTRY'
-          )
-        : undefined;
-
-    return countryRule && 'value' in countryRule && typeof countryRule.value === 'string'
-      ? countryRule.value
-      : '';
-  }, [data]);
-
-  const handleReloadCityOptions = React.useCallback(() => {
-    setCityReloadToken(token => token + 1);
-  }, []);
-
   React.useEffect(() => {
-    if (!cityRuleInUse) {
-      setCityOptionsStatus('idle');
-      builderRef.current?.clearFieldOptions('CITY');
-      return;
-    }
-
-    builderRef.current?.invalidateFieldOptions('CITY');
-    builderRef.current?.setFieldOptionsStatus('CITY', 'loading');
-    setCityOptionsStatus('loading');
-
-    const timeoutId = window.setTimeout(() => {
-      if (selectedCountry === 'CZ') {
-        builderRef.current?.setFieldOptions('CITY', [
-          { value: 'PRG', label: 'Prague' },
-          { value: 'BRN', label: 'Brno' },
-          { value: 'OSR', label: 'Ostrava' },
-        ]);
-      } else if (selectedCountry === 'SK') {
-        builderRef.current?.setFieldOptions('CITY', [
-          { value: 'BTS', label: 'Bratislava' },
-          { value: 'KSC', label: 'Kosice' },
-          { value: 'ZIL', label: 'Zilina' },
-        ]);
-      } else if (selectedCountry === 'DE') {
-        builderRef.current?.setFieldOptions('CITY', [
-          { value: 'BER', label: 'Berlin' },
-          { value: 'MUC', label: 'Munich' },
-          { value: 'HAM', label: 'Hamburg' },
-        ]);
-      } else {
-        builderRef.current?.setFieldOptions('CITY', []);
-      }
+    return builderRef.bindRuleOptions('CITY', {
+      dependencies: ['COUNTRY'],
+      resolve: async ({ dependencies, signal }) => {
+        const countryValue = dependencies.COUNTRY?.value;
 
-      setCityOptionsStatus('success');
-    }, 650);
+        if (typeof countryValue !== 'string') {
+          return [];
+        }
 
-    return () => window.clearTimeout(timeoutId);
-  }, [builderRef, cityRuleInUse, cityReloadToken, selectedCountry]);
+        await waitForTimeout(550, signal);
+        return cityOptionsByCountry[countryValue] ?? [];
+      },
+      onOptionsResolved: ({ ruleId }) => {
+        builderRef.reconcileRuleValueWithOptions(ruleId, {
+          strategy: 'clear-if-missing',
+        });
+      },
+    });
+  }, [builderRef]);
 
   return (
     <DemoCard>
-      <Toolbar>
-        <SmallButton
-          type="button"
-          onClick={() => {
-            const rootGroupId = builderRef.current
-              ?.getNodes()
-              .find((node) => 'type' in node)?.id;
-            const cityRuleId = builderRef.current
-              ?.getNodes()
-              .find((node) => 'field' in node && node.field === 'CITY')?.id;
-
-            if (cityRuleId) {
-              builderRef.current?.deleteNode(cityRuleId);
-              return;
-            }
-
-            if (rootGroupId) {
-              builderRef.current?.addRule(
-                {
-                  field: 'CITY',
-                  operator: 'EQUAL',
-                  value: '',
-                },
-                rootGroupId
-              );
-            }
-          }}
-        >
-          {cityRuleInUse ? 'Remove city rule' : 'Add city rule'}
-        </SmallButton>
-        <SmallButton
-          type="button"
-          onClick={() => builderRef.current?.reloadFieldOptions('CITY')}
-        >
-          Reload city options
-        </SmallButton>
-      </Toolbar>
-      <StatusRow>
-        <span>City rule in scope: {cityRuleInUse ? 'yes' : 'no'}</span>
-        <span>City options status: {cityOptionsStatus}</span>
-        <span>
-          Runtime options:{' '}
-          {builderRef.current?.getFieldOptionState('CITY').options.length ?? 0}
-        </span>
-      </StatusRow>
-      <Builder
-        ref={builderRef}
-        fields={fields}
-        data={data}
-        onFieldOptionsReload={(field) => {
-          if (field === 'CITY') {
-            handleReloadCityOptions();
-          }
-        }}
-        onChange={setData}
-      />
+      <Builder ref={builderRef} fields={fields} data={data} onChange={setData} />
     </DemoCard>
   );
 };