Merge pull request #63 from rtucek/max-depth-for-groups

Restrict maximum nesting of groups

Author: rtucek

dev/App.vue

@@ -1,10 +1,82 @@
 <template>
-  <div id="app">
+  <div class="container">
+    <div class="container-config">
+      <div class="container-config-item" >
+        <label for="ctrlEnableDragNDrop">
+          Allow Drag'n'drop
+        </label>
+        <input
+          type="checkbox"
+          v-model="ctrlEnableDragNDrop"
+          id="ctrlEnableDragNDrop"
+        >
+      </div>
+      <div class="container-config-item config-max-depth">
+        <div>
+          <label for="ctrlEnableMaxDepth">
+            Enable max depth
+          </label>
+          <input
+            type="checkbox"
+            v-model="ctrlEnableMaxDepth"
+            id="ctrlEnableMaxDepth"
+          >
+        </div>
+        <div>
+          <label for="ctrlMaxDepth">
+            Max Depth:
+          </label>
+          <input
+            v-model.number="ctrlMaxDepth"
+            type="number"
+            min="0"
+            :disabled="! ctrlEnableMaxDepth"
+            id="ctrlMaxDepth"
+          >
+        </div>
+      </div>
+      <div class="container-config-item config-slots">
+        <div>
+          <label for="ctrlEnableGroupOperatorSlot">
+            Enable Group Operator Slot
+          </label>
+          <input
+            type="checkbox"
+            v-model="ctrlEnableGroupOperatorSlot"
+            id="ctrlEnableGroupOperatorSlot"
+          >
+        </div>
+        <div>
+          <label for="ctrlEnableGroupControlSlot">
+            Enable Group Control Slot
+          </label>
+          <input
+            type="checkbox"
+            v-model="ctrlEnableGroupControlSlot"
+            id="ctrlEnableGroupControlSlot"
+          >
+        </div>
+        <div>
+          <label for="ctrlEnableRuleSlot">
+            Enable Rule Slot
+          </label>
+          <input
+            type="checkbox"
+            v-model="ctrlEnableRuleSlot"
+            id="ctrlEnableRuleSlot"
+          >
+        </div>
+      </div>
+    </div>
     <query-builder
-      :config="config"
+      :config="getConfig"
       v-model="query"
+      class ="query-builder"
     >
-      <template #groupOperator="props">
+      <template
+        v-if="ctrlEnableGroupOperatorSlot"
+        #groupOperator="props"
+      >
         <div class="query-builder-group-slot__group-selection">
           <span class="query-builder-group-slot__group-operator">SLOT #groupOperator</span>
           <select
@@ -22,11 +94,17 @@
         </div>
       </template>
 
-      <template #groupControl="props">
+      <template
+        v-if="ctrlEnableGroupControlSlot"
+        #groupControl="props"
+      >
         <group-ctrl-slot :group-ctrl="props"/>
       </template>
 
-      <template #rule="props">
+      <template
+        v-if="ctrlEnableRuleSlot"
+        #rule="props"
+      >
         <rule-slot :ruleCtrl="props"/>
       </template>
     </query-builder>
@@ -52,9 +130,25 @@ import RuleSlot from './RuleSlot.vue';
   },
 })
 export default class App extends Vue {
+ctrlEnableDragNDrop: boolean = true;
+
+  ctrlEnableMaxDepth: boolean = false;
+
+  ctrlMaxDepth: number = 3;
+
+  ctrlEnableGroupOperatorSlot: boolean = true;
+
+  ctrlEnableGroupControlSlot: boolean = true;
+
+  ctrlEnableRuleSlot: boolean = true;
+
   query: RuleSet | null = {
     operatorIdentifier: 'OR',
     children: [
+      {
+        identifier: 'txt',
+        value: 'A',
+      },
       {
         operatorIdentifier: 'AND',
         children: [
@@ -143,6 +237,7 @@ export default class App extends Vue {
         initialValue: 10,
       },
     ],
+    maxDepth: undefined,
     colors: [
       'hsl(88, 50%, 55%)',
       'hsl(187, 100%, 45%)',
@@ -154,6 +249,22 @@ export default class App extends Vue {
       ghostClass: 'ghost',
     },
   }
+
+  get getConfig(): QueryBuilderConfig {
+    const config: QueryBuilderConfig = { ...this.config };
+
+    if (!config.dragging) {
+      config.dragging = {};
+    }
+    config.dragging.disabled = !this.ctrlEnableDragNDrop;
+
+    config.maxDepth = Math.abs(this.ctrlMaxDepth || 0);
+    if (!this.ctrlEnableMaxDepth) {
+      config.maxDepth = undefined;
+    }
+
+    return config;
+  }
 }
 </script>
 
@@ -167,9 +278,30 @@ body {
   font-size: 16px;
 }
 
-#app {
-  margin: 30px auto;
+.container {
   width: 90%;
+  margin: 30px auto;
+  display: flex;
+  flex-direction: column;
+}
+
+.container-config {
+  border: 1px solid hsl(0, 0%, 75%);
+  margin-bottom: 30px;
+  padding: 10px;
+  display: grid;
+  grid-template-columns: 1fr 1fr 1fr;
+}
+
+// .container-config-item {
+//
+// }
+
+.config-max-depth #ctrlMaxDepth {
+  width: 70px;
+}
+
+.query-builder {
   border: 1px solid hsl(0, 0%, 75%);
 }
 

dev/GroupCtrlSlot.vue

@@ -32,13 +32,15 @@ export default class GroupCtrlSlot extends Vue {
     >
       Add Rule
     </button>
-    <div class="query-builder-group-slot__spacer"/>
-    <button
-      @click="groupCtrl.newGroup"
-      class="query-builder-group-slot__group-adding-button"
-    >
-      Add Group
-    </button>
+    <template v-if="! groupCtrl.maxDepthExeeded">
+      <div class="query-builder-group-slot__spacer"/>
+      <button
+        @click="groupCtrl.newGroup"
+        class="query-builder-group-slot__group-adding-button"
+      >
+        Add Group
+      </button>
+    </template>
   </div>
 </template>
 

docs/configuration.md

@@ -155,10 +155,10 @@ Vue.component('NumberSelection', {
 
 ## Colors
 
-A complex, deep nested query can quickly become confusing. In order to keep an overview, nested
+A complex, deep nested query, can quickly become confusing. In order to keep an overview, nested
 groups may be emphasized with colorful hints.
 
-The colors property should be a string array with a minimum length of at least 2, containing any
+The `colors` property should be a string array with a minimum length of at least 2, containing any
 valid CSS color definition.
 
 
@@ -222,3 +222,37 @@ for allowing nested dragging.
   allow="geolocation; microphone; camera; midi; vr; accelerometer; gyroscope; payment; ambient-light-sensor; encrypted-media; usb"
   sandbox="allow-modals allow-forms allow-popups allow-scripts allow-same-origin"
 ></iframe>
+
+
+## Max-Depth
+
+If `typeof maxDepth === 'undefined'`, users may have an arbitrary depth of nested groups.
+
+For `typeof maxDepth === 'number' and 0 <= n <= maxDepth`, users are only allowed to create up to n
+nested groups. If n is 0, users are effectively not allowed to create any groups at all.
+
+
+### Runtime change
+
+It is possible and valid to change `maxDepth` at runtime.
+As a special chase, if the given query has a higher nested depth and a config change restricts the
+`maxDepth` to a lower depth, the library (intentionally) removes any child groups, exceeding the
+present config limit. This ensures consistency with the `maxDepth` policy. It's the component user's
+responsibility of checking if setting `maxDepth` may not result in an unwanted side-effect of
+removing any child-groups from the given query tree.
+
+
+### Usage of Sortable
+
+If drag'n'drop is activated via [Sortable](#sortable) config:
+Prior dropping a dragged group into another group, the library checks if the max depth policy would
+be violated and prevents dropping. The user will notice that the drag'n'drop preview will not adjust
+as usually expected.
+
+
+### Usage of groupCtrlSlotProps
+
+For the slot of type [`groupCtrlSlotProps`](styling.html#groupcontrol-slot), the `newGroup()`
+callback, passed as slot prop, becomes a noop, if a group has exceeded the `maxDepth` policy.
+Additionally, a boolean flag with a `maxDepthExeeded` property is provided to the slot prop object,
+so the slot can check and hide a create-new-group handler.

docs/styling.md

@@ -23,7 +23,7 @@ Often, you'll have to use `v-bind:value` and `v-on:input` instead.
 The `groupOperator` slot may be used for changing the markup of a group's operator.
 
 The slot receives an object with the shape of the [GroupOperatorSlotProps
-object](https://github.com/rtucek/vue-query-builder/blob/master/types/index.d.ts#L33).
+object](https://github.com/rtucek/vue-query-builder/blob/master/types/index.d.ts#L34).
 
 ```vue
 <template>
@@ -73,7 +73,7 @@ object](https://github.com/rtucek/vue-query-builder/blob/master/types/index.d.ts
 The `groupControl` slot allows for creating a new group or adding a new rule.
 
 The slot receives an object with the shape of the [GroupCtrlSlotProps
-object](https://github.com/rtucek/vue-query-builder/blob/master/types/index.d.ts#L39).
+object](https://github.com/rtucek/vue-query-builder/blob/master/types/index.d.ts#L40).
 
 <iframe
   src="https://codesandbox.io/embed/groupcontrol-slot-8thx1?fontsize=14&hidenavigation=1&module=%2Fsrc%2FApp.vue&theme=dark"
@@ -89,7 +89,7 @@ object](https://github.com/rtucek/vue-query-builder/blob/master/types/index.d.ts
 The `rule` slot allows for customizing markup around each rule component.
 
 The slot receives an object with the shape of the [RuleSlotProps
-object](https://github.com/rtucek/vue-query-builder/blob/master/types/index.d.ts#L45).
+object](https://github.com/rtucek/vue-query-builder/blob/master/types/index.d.ts#L47).
 
 You'll have to use Vue's [Dynamic
 Component](https://vuejs.org/v2/guide/components.html#Dynamic-Components) feature for displaying the