@react-querybuilder/core 8.22.1 → 8.22.3

package/dist/cjs/react-querybuilder_core.cjs.development.d.ts

@@ -5671,6 +5671,14 @@ interface QueryManagerOptions<F extends FullField = FullField, O extends FullOpe
   autoSelectOperator?: boolean;
   /** When `false`, an empty placeholder option is prepended to each value list. */
   autoSelectValue?: boolean;
+  /**
+   * Translations, accepting the same shape as the `translations` prop. Only the placeholder
+   * properties of `fields`, `operators`, and `values` are used, and only when the corresponding
+   * `autoSelect*` option is `false`; the remaining keys describe UI elements that have no
+   * meaning outside the `QueryBuilder` component. Labels are typed as `unknown` so the React
+   * `Translations` type, whose labels are `ReactNode`, can be passed as-is.
+   */
+  translations?: Partial<BaseTranslations<unknown>>;
   /** The default `field` for rules created by {@link QueryManager.createRule}. */
   getDefaultField?: string | ((fieldsData: FullOptionList<F>) => string);
   /** The default `operator` for a given field. */
@@ -5885,6 +5893,50 @@ declare class QueryManager<RG extends RuleGroupTypeAny = RuleGroupType, F extend
    * `targetPathOrID` and `sourcePathOrID`.
    */
   group(sourcePathOrID: Path | string, targetPathOrID: Path | string, options?: GroupOptions & StrictOptions): this;
+  /**
+   * The options currently in effect, as a frozen shallow copy. Reflects everything applied by
+   * the constructor and any subsequent {@link QueryManager.reconfigure} calls, but not the
+   * defaults filled in for options that were never provided.
+   */
+  getOptions(): Readonly<QueryManagerOptions<F, O, C>>;
+  /**
+   * Updates the manager's configuration in place, keeping the current query, the undo/redo
+   * history, and every subscriber. Use this to propagate new `translations`, `fields`,
+   * `operators`, and so on without discarding state:
+   *
+   * ```ts
+   * q.reconfigure({ translations: { fields: { placeholderLabel: 'Choisir un champ' } } });
+   * ```
+   *
+   * The incoming options are shallow-merged over the current ones, so keys left out are
+   * preserved. Passing a key explicitly as `undefined` resets it to its default. Object-valued
+   * options like `translations` are replaced wholesale rather than deep-merged — spread the
+   * current value in yourself to patch one key. Pass `{ replace: true }` to discard the
+   * existing options entirely and start from the incoming set.
+   *
+   * The query is never rewritten, even when the new options no longer describe it: a rule whose
+   * `field` is not in the new `fields` list is left as-is. Call
+   * {@link QueryManager.validate validate} to detect that, or `setQuery(getQuery())` to
+   * re-normalize.
+   *
+   * History options are honored immediately: lowering `maxHistory` trims the undo stack, and
+   * turning history off clears both stacks. Subscribers are notified once, and
+   * {@link QueryManager.getConfigVersion} is incremented, even inside a
+   * {@link QueryManager.batch batch} — configuration is not part of a batch's rollback.
+   */
+  reconfigure(options: Partial<QueryManagerOptions<F, O, C>>, config?: {
+    replace?: boolean;
+  }): this;
+  /**
+   * A counter incremented by every {@link QueryManager.reconfigure} call. Because reconfiguring
+   * leaves the query object untouched, subscribers that compare query identity alone cannot see
+   * it; this provides a snapshot that does change.
+   *
+   * Bound to the instance, so it can be passed directly to `useSyncExternalStore` alongside
+   * {@link QueryManager.subscribe}. The `useQueryManager` hook from `react-querybuilder`
+   * already does this.
+   */
+  getConfigVersion: () => number;
   /**
    * Creates an independent manager with the same configuration and the current query.
    *

package/dist/cjs/react-querybuilder_core.cjs.development.js

@@ -6785,6 +6785,8 @@ var QueryManager = class QueryManager {
 	#maxHistory;
 	#coalesceMs;
 	#now;
+	/** Incremented by every {@link QueryManager.reconfigure} call. See `getConfigVersion`. */
+	#configVersion = 0;
 	#past = [];
 	#future = [];
 	#lastSig;
@@ -6802,6 +6804,15 @@ var QueryManager = class QueryManager {
 	#idPathIndex;
 	#validation;
 	constructor(query, options = {}) {
+		this.#applyOptions(options);
+		this.#query = (0, immer.freeze)(query ? prepareRuleGroup(query, { idGenerator: this.#idGenerator }) : this.createRuleGroup(), true);
+	}
+	/**
+	* Assigns `#options` and every field derived from it. Shared by the constructor and
+	* {@link QueryManager.reconfigure}, so the two can never drift apart. Does not touch the
+	* query, the history stacks, the caches, or the subscriber list.
+	*/
+	#applyOptions(options) {
 		this.#options = options;
 		this.#idGenerator = options.idGenerator ?? generateID;
 		this.#validator = options.validator ?? defaultValidator;
@@ -6817,7 +6828,8 @@ var QueryManager = class QueryManager {
 		const { optionList: fields, optionsMap: fieldMap } = prepareOptionList({
 			optionList: options.fields,
 			baseOption: options.baseField,
-			autoSelectOption: options.autoSelectField
+			autoSelectOption: options.autoSelectField,
+			placeholder: options.translations?.fields
 		});
 		this.#fields = (0, immer.freeze)(fields, true);
 		this.#fieldMap = (0, immer.freeze)(fieldMap, true);
@@ -6825,13 +6837,13 @@ var QueryManager = class QueryManager {
 			optionList: options.operators ?? defaultOperators,
 			baseOption: options.baseOperator,
 			labelMap: defaultOperatorLabelMap,
-			autoSelectOption: options.autoSelectOperator
+			autoSelectOption: options.autoSelectOperator,
+			placeholder: options.translations?.operators
 		}).optionList;
 		this.#combinators = (0, immer.freeze)(prepareOptionList({
 			optionList: options.combinators ?? defaultCombinators,
 			baseOption: options.baseCombinator
 		}).optionList, true);
-		this.#query = (0, immer.freeze)(query ? prepareRuleGroup(query, { idGenerator: this.#idGenerator }) : this.createRuleGroup(), true);
 	}
 	/** Resolves the field configuration for a field name. */
 	#fieldData(field) {
@@ -6845,7 +6857,8 @@ var QueryManager = class QueryManager {
 			getOperators: this.#options.getOperators,
 			operators: this.#operators,
 			baseOption: this.#options.baseOperator,
-			autoSelectOption: this.#options.autoSelectOperator
+			autoSelectOption: this.#options.autoSelectOperator,
+			placeholder: this.#options.translations?.operators
 		});
 	}
 	/** Resolves the default operator for a field, mirroring `QueryBuilder`'s precedence. */
@@ -6869,7 +6882,8 @@ var QueryManager = class QueryManager {
 			operator,
 			fieldData: this.#fieldData(field),
 			getValues: this.#options.getValues,
-			autoSelectOption: this.#options.autoSelectValue
+			autoSelectOption: this.#options.autoSelectValue,
+			placeholder: this.#options.translations?.values
 		});
 	}
 	#valueEditorTypeFor(field, operator) {
@@ -7165,6 +7179,79 @@ var QueryManager = class QueryManager {
 		return this;
 	}
 	/**
+	* The options currently in effect, as a frozen shallow copy. Reflects everything applied by
+	* the constructor and any subsequent {@link QueryManager.reconfigure} calls, but not the
+	* defaults filled in for options that were never provided.
+	*/
+	getOptions() {
+		return (0, immer.freeze)({ ...this.#options });
+	}
+	/**
+	* Updates the manager's configuration in place, keeping the current query, the undo/redo
+	* history, and every subscriber. Use this to propagate new `translations`, `fields`,
+	* `operators`, and so on without discarding state:
+	*
+	* ```ts
+	* q.reconfigure({ translations: { fields: { placeholderLabel: 'Choisir un champ' } } });
+	* ```
+	*
+	* The incoming options are shallow-merged over the current ones, so keys left out are
+	* preserved. Passing a key explicitly as `undefined` resets it to its default. Object-valued
+	* options like `translations` are replaced wholesale rather than deep-merged — spread the
+	* current value in yourself to patch one key. Pass `{ replace: true }` to discard the
+	* existing options entirely and start from the incoming set.
+	*
+	* The query is never rewritten, even when the new options no longer describe it: a rule whose
+	* `field` is not in the new `fields` list is left as-is. Call
+	* {@link QueryManager.validate validate} to detect that, or `setQuery(getQuery())` to
+	* re-normalize.
+	*
+	* History options are honored immediately: lowering `maxHistory` trims the undo stack, and
+	* turning history off clears both stacks. Subscribers are notified once, and
+	* {@link QueryManager.getConfigVersion} is incremented, even inside a
+	* {@link QueryManager.batch batch} — configuration is not part of a batch's rollback.
+	*/
+	reconfigure(options, config) {
+		this.#applyOptions((0, immer.freeze)(config?.replace ? { ...options } : {
+			...this.#options,
+			...options
+		}));
+		this.#validation = void 0;
+		this.#reconcileHistoryConfig();
+		++this.#configVersion;
+		this.#notify();
+		return this;
+	}
+	/**
+	* Brings the history stacks in line with the current history configuration. Unlike
+	* {@link QueryManager.clearHistory}, this does _not_ set `#historyBypassed`: it reflects a
+	* configuration change rather than a deliberate history repositioning, so a later mutation in
+	* the same batch must still be recorded normally.
+	*
+	* Called by {@link QueryManager.reconfigure} and again after a failed
+	* {@link QueryManager.batch batch} restores its snapshot, since that snapshot predates the
+	* configuration change (configuration is not part of a batch's rollback).
+	*/
+	#reconcileHistoryConfig() {
+		if (this.#historyEnabled) {
+			if (this.#past.length > this.#maxHistory) this.#past.splice(0, this.#past.length - this.#maxHistory);
+		} else {
+			this.#past = [];
+			this.#future = [];
+			this.#lastSig = void 0;
+		}
+	}
+	/**
+	* A counter incremented by every {@link QueryManager.reconfigure} call. Because reconfiguring
+	* leaves the query object untouched, subscribers that compare query identity alone cannot see
+	* it; this provides a snapshot that does change.
+	*
+	* Bound to the instance, so it can be passed directly to `useSyncExternalStore` alongside
+	* {@link QueryManager.subscribe}. The `useQueryManager` hook from `react-querybuilder`
+	* already does this.
+	*/
+	getConfigVersion = () => this.#configVersion;
+	/**
 	* Creates an independent manager with the same configuration and the current query.
 	*
 	* Subscribers and history are _not_ carried over: the clone starts with no listeners and an
@@ -7232,6 +7319,7 @@ var QueryManager = class QueryManager {
 				this.#future = snapshot.future;
 				this.#lastSig = snapshot.lastSig;
 				this.#lastAt = snapshot.lastAt;
+				this.#reconcileHistoryConfig();
 			}
 			throw error;
 		} finally {