feat: Added lockable functionality into GUI

Author: Vojtěch Václav Porteš

README.md

@@ -74,6 +74,12 @@ const initialData: DenormalizedQuery = [
     value: 'AND',
     isNegated: false,
     children: [
+      {
+        field: 'STATE',
+        operator: 'EQUAL',
+        value: 'CZ',
+        readOnly: true,
+      },
       {
         field: 'IS_IN_EU',
         operator: 'EQUAL',

example/src/components/demo-playground.tsx

@@ -116,6 +116,7 @@ export const DemoPlayground: React.FC<IDemoPlaygroundProps> = ({
   const [data, setData] = React.useState<DenormalizedQuery>(initialData);
   const [outputFormat, setOutputFormat] = React.useState<OutputFormat>('Native');
   const [readOnly, setReadOnly] = React.useState(false);
+  const [lockable, setLockable] = React.useState(false);
   const [draggable, setDraggable] = React.useState(false);
   const [singleRootGroup, setSingleRootGroup] = React.useState(true);
   const [showValidation, setShowValidation] = React.useState(true);
@@ -146,6 +147,15 @@ export const DemoPlayground: React.FC<IDemoPlaygroundProps> = ({
             <span>Read-only mode</span>
           </ToggleRow>
 
+          <ToggleRow>
+            <Toggle
+              type="checkbox"
+              checked={lockable}
+              onChange={event => setLockable(event.target.checked)}
+            />
+            <span>Lock controls</span>
+          </ToggleRow>
+
           <ToggleRow>
             <Toggle
               type="checkbox"
@@ -187,6 +197,7 @@ export const DemoPlayground: React.FC<IDemoPlaygroundProps> = ({
                 data={data}
                 fields={demoFields}
                 readOnly={readOnly}
+                lockable={lockable}
                 onChange={setData}
                 draggable={draggable}
                 groupTypes="both"

example/src/constants/demo-data.ts

@@ -134,6 +134,7 @@ export const initialQueryTree: DenormalizedQuery = [
         field: 'CUSTOMER_COUNTRY',
         operator: 'EQUAL',
         value: 'CZ',
+        readOnly: true,
       },
       {
         type: 'GROUP',

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

@@ -15,6 +15,7 @@ const builderSignature = `export interface IBuilderProps {
   components?: IBuilderComponentsProps;
   strings?: IStrings;
   readOnly?: boolean;
+  lockable?: boolean;
   draggable?: boolean;
   singleRootGroup?: boolean;
   groupTypes?: 'with-modifiers' | 'without-modifiers' | 'both';
@@ -92,6 +93,7 @@ const componentsSignature = `export interface IBuilderComponentsProps {
   };
   Remove?: React.ComponentType<IButtonProps>;
   Add?: React.ComponentType<IButtonProps>;
+  LockToggle?: React.ComponentType<ILockToggleProps>;
   Rule?: React.ComponentType<IRuleContainerProps>;
   Group?: React.ComponentType<IGroupContainerProps>;
   GroupHeaderOption?: React.ComponentType<IGroupHeaderOptionProps>;
@@ -102,6 +104,18 @@ const componentsSignature = `export interface IBuilderComponentsProps {
   PopoverItem?: React.ComponentType<IPopoverItemProps>;
 }`;
 
+const lockToggleSignature = `export type BuilderLockState = 'unlocked' | 'self' | 'all';
+
+export interface ILockToggleProps {
+  state: BuilderLockState;
+  nodeType: 'rule' | 'group';
+  disabled?: boolean;
+  onChange?: (nextState: BuilderLockState) => void;
+  className?: string;
+  title?: string;
+  'data-test'?: string;
+}`;
+
 const themeProviderSignature = `export interface IThemeProps {
   colors?: IColors;
 }
@@ -275,6 +289,7 @@ export const apiPages: IApiPage[] = [
           <li><ItemTitle><InlineCode>components</InlineCode>:</ItemTitle> Optional overrides for internal UI pieces. Omitted entries fall back to default components.</li>
           <li><ItemTitle><InlineCode>strings</InlineCode>:</ItemTitle> Optional localized UI strings used by the built-in controls.</li>
           <li><ItemTitle><InlineCode>readOnly</InlineCode>:</ItemTitle> Defaults to <InlineCode>false</InlineCode>. Disables editing actions when enabled.</li>
+          <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.</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>singleRootGroup</InlineCode>:</ItemTitle> Defaults to <InlineCode>true</InlineCode>. Wraps root-level items into a single root group and prevents deleting that root group.</li>
           <li><ItemTitle><InlineCode>groupTypes</InlineCode>:</ItemTitle> Defaults to <InlineCode>'with-modifiers'</InlineCode>. Controls whether groups use combinator/negation controls, modifierless groups, or both.</li>
@@ -346,6 +361,7 @@ export const apiPages: IApiPage[] = [
           <li><ItemTitle><InlineCode>value</InlineCode>:</ItemTitle> Optional rule value. Supported scalar/array forms are defined by <InlineCode>QueryRuleValue</InlineCode>.</li>
           <li><ItemTitle><InlineCode>operators</InlineCode>:</ItemTitle> Optional rule-level operator override list.</li>
           <li><ItemTitle><InlineCode>readOnly</InlineCode>:</ItemTitle> Optional per-rule lock flag. It locks only that rule and does not affect siblings, parents, or descendants.</li>
+          <li><ItemTitle>GUI cycle:</ItemTitle> When <InlineCode>lockable</InlineCode> is enabled, rules cycle between unlocked and locked, which maps to omitted <InlineCode>readOnly</InlineCode> and <InlineCode>readOnly: true</InlineCode>.</li>
           <li><ItemTitle><InlineCode>id</InlineCode> and <InlineCode>parent</InlineCode>:</ItemTitle> Optional in denormalized input. The builder can ingest data without them.</li>
         </List>
         <SectionTitle>Group props</SectionTitle>
@@ -356,6 +372,7 @@ export const apiPages: IApiPage[] = [
           <li><ItemTitle><InlineCode>isNegated</InlineCode>:</ItemTitle> Present only for groups with modifiers.</li>
           <li><ItemTitle><InlineCode>readOnly</InlineCode>:</ItemTitle> Can be a boolean or an object with <InlineCode>enabled</InlineCode> and optional <InlineCode>inheritToChildren</InlineCode>.</li>
           <li><ItemTitle><InlineCode>readOnly: true</InlineCode>:</ItemTitle> Locks only the group&apos;s own controls by default. Descendant rules and groups remain editable unless inheritance is enabled.</li>
+          <li><ItemTitle>GUI cycle:</ItemTitle> When <InlineCode>lockable</InlineCode> is enabled, groups cycle through unlocked, locked group only, and locked group with descendants.</li>
           <li><ItemTitle><InlineCode>inheritToChildren</InlineCode>:</ItemTitle> Applies the group lock to all descendants when the group is enabled. Descendants cannot override an inherited lock from an ancestor.</li>
         </List>
         <AlertBox title="Documentation" variant="info">
@@ -378,10 +395,12 @@ export const apiPages: IApiPage[] = [
     content: (
       <>
         <CodeBlock code={componentsSignature} language="ts" label="Component overrides" />
+        <CodeBlock code={lockToggleSignature} language="ts" label="LockToggle props" />
         <SectionTitle>Props</SectionTitle>
         <List>
           <li><ItemTitle><InlineCode>form.Select</InlineCode> / <InlineCode>form.SelectMulti</InlineCode> / <InlineCode>form.Switch</InlineCode> / <InlineCode>form.Input</InlineCode>:</ItemTitle> Replace the built-in form controls used by rules and groups.</li>
           <li><ItemTitle><InlineCode>Remove</InlineCode> and <InlineCode>Add</InlineCode>:</ItemTitle> Replace action buttons used for structural editing.</li>
+          <li><ItemTitle><InlineCode>LockToggle</InlineCode>:</ItemTitle> Replaces the built-in lock control used when <InlineCode>lockable</InlineCode> is enabled.</li>
           <li><ItemTitle><InlineCode>Rule</InlineCode> and <InlineCode>Group</InlineCode>:</ItemTitle> Replace the main structural containers.</li>
           <li><ItemTitle><InlineCode>GroupHeaderOption</InlineCode>:</ItemTitle> Replaces the header option control used in group UIs.</li>
           <li><ItemTitle><InlineCode>Text</InlineCode>:</ItemTitle> Replaces the built-in text rendering component.</li>
@@ -394,6 +413,7 @@ export const apiPages: IApiPage[] = [
           <li><ItemTitle><InlineCode>form.Select</InlineCode>:</ItemTitle> Receives <InlineCode>values</InlineCode>, <InlineCode>selectedValue</InlineCode>, <InlineCode>emptyValue</InlineCode>, and <InlineCode>onChange(value)</InlineCode>.</li>
           <li><ItemTitle><InlineCode>form.SelectMulti</InlineCode>:</ItemTitle> Receives <InlineCode>selectedValue</InlineCode>, <InlineCode>values</InlineCode>, <InlineCode>onChange(value)</InlineCode>, and <InlineCode>onDelete(value)</InlineCode>.</li>
           <li><ItemTitle><InlineCode>form.Switch</InlineCode>:</ItemTitle> Receives <InlineCode>switched</InlineCode>, optional <InlineCode>onChange(value)</InlineCode>, and optional <InlineCode>disabled</InlineCode>.</li>
+          <li><ItemTitle><InlineCode>LockToggle</InlineCode>:</ItemTitle> Receives <InlineCode>state</InlineCode>, <InlineCode>nodeType</InlineCode>, optional <InlineCode>disabled</InlineCode>, and <InlineCode>onChange(nextState)</InlineCode>.</li>
           <li><ItemTitle><InlineCode>Rule</InlineCode>:</ItemTitle> Receives already-built <InlineCode>children</InlineCode>, <InlineCode>controls</InlineCode>, and optional <InlineCode>dragHandle</InlineCode>.</li>
           <li><ItemTitle><InlineCode>Group</InlineCode>:</ItemTitle> Receives <InlineCode>controlsLeft</InlineCode>, <InlineCode>controlsRight</InlineCode>, <InlineCode>children</InlineCode>, and optional overlays or drag handles.</li>
           <li><ItemTitle><InlineCode>DropZone</InlineCode>:</ItemTitle> Receives <InlineCode>id</InlineCode>, <InlineCode>index</InlineCode>, optional <InlineCode>parentId</InlineCode>, and drag-state flags.</li>

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

@@ -58,6 +58,12 @@ const initialData: DenormalizedQuery = [
     value: 'AND',
     isNegated: false,
     children: [
+      {
+        field: 'STATE',
+        operator: 'EQUAL',
+        value: 'CZ',
+        readOnly: true,
+      },
       {
         field: 'IS_IN_EU',
         operator: 'EQUAL',
@@ -186,12 +192,17 @@ const validationSnippet = `const fields: IBuilderFieldProps[] = [
 const builderBehaviorSnippet = `<Builder
   fields={fields}
   data={data}
+  lockable
   draggable
   singleRootGroup={false}
   groupTypes="both"
   onChange={setData}
 />;
 
+// lockable:
+// Renders built-in lock controls for rules and groups and writes the resulting
+// lock state back into the emitted query via rule/group readOnly values.
+//
 // draggable:
 // Enables drag-and-drop for editable rules and groups.
 //
@@ -248,6 +259,42 @@ const lockingSnippet = `const data: DenormalizedQuery = [
 
 <Builder fields={fields} data={data} onChange={setData} />;`;
 
+const lockingGuiSnippet = `<Builder
+  fields={fields}
+  data={data}
+  lockable
+  onChange={setData}
+/>;
+
+// Rules cycle through:
+// unlocked -> locked
+//
+// Groups cycle through:
+// unlocked -> locked group only -> locked group and descendants
+//
+// The emitted query stores those states in readOnly:
+// rule: readOnly: true
+// group: readOnly: true
+// group + descendants: readOnly: { enabled: true, inheritToChildren: true }`;
+
+const lockToggleSnippet = `const components = {
+  LockToggle: MyLockToggle,
+};
+
+<Builder
+  fields={fields}
+  data={data}
+  lockable
+  components={components}
+  onChange={setData}
+/>;
+
+// LockToggle receives:
+// state: 'unlocked' | 'self' | 'all'
+// nodeType: 'rule' | 'group'
+// disabled?: boolean
+// onChange?: (nextState) => void`;
+
 const stringsSnippet = `import { strings } from '@vojtechportes/react-query-builder';
 
 <Builder
@@ -351,6 +398,11 @@ export const documentationPages: IDocumentationPage[] = [
       <>
         <p>Basic controlled usage.</p>
         <CodeBlock code={basicUsageSnippet} language="tsx" label="Basic setup" />
+        <p>
+          The example includes a single rule with <InlineCode>readOnly: true</InlineCode>{' '}
+          to show that locking can live directly in the query data without changing
+          the rest of the builder configuration.
+        </p>
         <AlertBox title="API reference" variant="info">
           <TextLink to="/api/builder">Builder</TextLink>,{' '}
           <TextLink to="/api/fields">Fields</TextLink>, and{' '}
@@ -428,6 +480,7 @@ export const documentationPages: IDocumentationPage[] = [
         <CodeBlock code={builderBehaviorSnippet} language="tsx" label="Builder behavior" />
         <SectionTitle>draggable</SectionTitle>
         <List>
+          <li>Use <InlineCode>lockable</InlineCode> to expose lock controls directly in the UI.</li>
           <li>Enables drag-and-drop reordering and movement for editable rules and groups.</li>
           <li>Read-only rules and groups are excluded from dragging.</li>
           <li>When the entire builder is read-only, drag-and-drop is disabled as well.</li>
@@ -487,6 +540,20 @@ export const documentationPages: IDocumentationPage[] = [
           distinction is that rules lock only themselves, while groups can lock
           either just their own controls or their entire subtree.
         </p>
+        <SectionTitle>GUI Locking</SectionTitle>
+        <p>
+          Set <InlineCode>lockable</InlineCode> on <TextLink to="/api/builder">Builder</TextLink>{' '}
+          to render lock controls directly in the UI. The built-in controls update
+          the same <InlineCode>readOnly</InlineCode> fields that are already part of
+          the query data model, so the resulting lock state is preserved in output.
+        </p>
+        <CodeBlock code={lockingGuiSnippet} language="tsx" label="GUI locking" />
+        <List>
+          <li>Rules cycle through two states: unlocked and locked.</li>
+          <li>Groups cycle through three states: unlocked, locked group only, and locked group with descendants.</li>
+          <li>The default group cycle maps to <InlineCode>false</InlineCode>, <InlineCode>true</InlineCode>, and <InlineCode>{`{ enabled: true, inheritToChildren: true }`}</InlineCode>.</li>
+          <li>When a parent group inherits a lock to descendants, child lock controls render disabled because descendants cannot override that inherited state.</li>
+        </List>
         <SectionTitle>How each level behaves</SectionTitle>
         <List>
           <li>
@@ -508,6 +575,12 @@ export const documentationPages: IDocumentationPage[] = [
           </li>
         </List>
         <CodeBlock code={lockingSnippet} language="tsx" label="Locking examples" />
+        <SectionTitle>Custom Lock Control</SectionTitle>
+        <p>
+          The default lock button can be replaced through{' '}
+          <InlineCode>components.LockToggle</InlineCode>.
+        </p>
+        <CodeBlock code={lockToggleSnippet} language="tsx" label="LockToggle override" />
         <SectionTitle>What &quot;locked&quot; means in the UI</SectionTitle>
         <List>
           <li>Locked rules cannot change field, operator, or value, and cannot be deleted.</li>

src/builder-context.tsx

@@ -13,6 +13,7 @@ export interface IBuilderContextProps {
   fields: IBuilderFieldProps[];
   data: NormalizedQuery;
   readOnly: boolean;
+  lockable?: boolean;
   draggable?: boolean;
   singleRootGroup?: boolean;
   groupTypes?: BuilderGroupMode;
@@ -35,6 +36,7 @@ export interface IBuilderContextProviderProps {
   fields: IBuilderFieldProps[];
   data: NormalizedQuery;
   readOnly: boolean;
+  lockable?: boolean;
   draggable?: boolean;
   singleRootGroup?: boolean;
   groupTypes?: BuilderGroupMode;
@@ -56,6 +58,7 @@ export const BuilderContextProvider: FC<IBuilderContextProviderProps> = ({
   strings,
   data,
   readOnly,
+  lockable,
   draggable,
   singleRootGroup,
   groupTypes,
@@ -105,6 +108,7 @@ export const BuilderContextProvider: FC<IBuilderContextProviderProps> = ({
         strings: resolvedStrings,
         data,
         readOnly,
+        lockable,
         draggable,
         singleRootGroup,
         groupTypes,