feat(QIntersection): new prop "root" (quasarframework#7861)

hawkeye64 · web-flow · commit 690bb69e3598 · 2020-10-03T19:14:22.000+03:00
Uses Intersection directive "root" config. Using the "root" property allows an ancestor to be defined. Currently, none of the QIntersection/Intersection examples work on Codepen. I have added one for QIntersection that will work because it uses it's immediate parent as root.
diff --git a/docs/src/examples/QIntersection/Root.vue b/docs/src/examples/QIntersection/Root.vue
@@ -0,0 +1,38 @@
+<template>
+  <div class="q-pa-md">
+    <div ref="myList" class="row justify-center q-gutter-sm">
+      <q-intersection
+        v-for="index in 60"
+        :key="index"
+        :root="listEl"
+        transition="scale"
+        class="example-item"
+      >
+        <q-card class="q-ma-sm">
+          <img src="https://cdn.quasar.dev/img/mountains.jpg">
+
+          <q-card-section>
+            <div class="text-h6">Card #{{ index }}</div>
+            <div class="text-subtitle2">by John Doe</div>
+          </q-card-section>
+        </q-card>
+      </q-intersection>
+    </div>
+  </div>
+</template>
+
+<script>
+export default {
+  computed: {
+    listEl () {
+      return this.$refs.myList ? this.$refs.myList.$el : null
+    }
+  }
+}
+</script>
+
+<style lang="sass" scoped>
+.example-item
+  height: 290px
+  width: 290px
+</style>
diff --git a/docs/src/pages/vue-components/intersection.md b/docs/src/pages/vue-components/intersection.md
@@ -32,23 +32,31 @@ An example of such needed CSS would be, for example, a fixed height or at least
 If using the `transition` prop, it is required that the content be wrapped in one and only one element.
 :::
 
+::: tip
+There are edge cases where the default viewport won't work. For instance, when your code is hosted in an iframe (like Codepen). This is where you need to use the `root` property. It allows you define an alternative to the viewport as your root (through its DOM element). It is important to keep in mind that root needs to be an ancestor of the observed element.
+:::
+
 ### Basic
 
-<doc-example title="Basic" file="QIntersection/Basic" scrollable />
+<doc-example title="Basic" file="QIntersection/Basic" scrollable no-edit />
 
 ### With transition
 
 In the example below we used a Quasar transition. For a full list, please head to [Transitions](/options/transitions) page.
 
-<doc-example title="With transition" file="QIntersection/Transition" scrollable />
+<doc-example title="With transition" file="QIntersection/Transition" scrollable no-edit />
 
-<doc-example title="A list with transition" file="QIntersection/List" scrollable />
+<doc-example title="A list with transition" file="QIntersection/List" scrollable no-edit />
 
 ### Only once
 
 Triggering only once means, however, that you lose the benefit of freeing up the DOM tree. The content will remain in DOM regardless of visibility.
 
-<doc-example title="Triggering only once" file="QIntersection/Once" scrollable />
+<doc-example title="Triggering only once" file="QIntersection/Once" scrollable no-edit />
+
+The example below uses the `root` property and therefore can be seen in a Codepen (which hosts in an iframe).
+
+<doc-example title="Root viewport" file="QIntersection/Root" scrollable />
 
 ## QIntersection API
 <doc-api file="QIntersection" />
diff --git a/docs/src/pages/vue-directives/intersection.md b/docs/src/pages/vue-directives/intersection.md
@@ -50,31 +50,31 @@ Scroll within the examples below until the observed element is in view. Then scr
 
 ### Basic
 
-<doc-example title="Basic" file="Intersection/Basic" />
+<doc-example title="Basic" file="Intersection/Basic" no-edit />
 
 ### Trigger once
 
 The directive can be used with the `once` modifier (ex: `v-intersection.once`). Once the observed element comes into view, the handler Function will be called and the observing will stop. This allows you to control the processing overhead if all you need is to be notified when the observed element starts to be visible on screen.
 
-<doc-example title="Once" file="Intersection/Once" />
+<doc-example title="Once" file="Intersection/Once" no-edit />
 
 ### Using an Object
 
 By passing in an Object as the directive's value (instead of a Function), you can control all the options (like threshold) of the Intersection Observer.
 
-<doc-example title="Supplying configuration Object" file="Intersection/ObjectForm" />
+<doc-example title="Supplying configuration Object" file="Intersection/ObjectForm" no-edit />
 
 ### Advanced
 
 Below is a more advanced example of what you can do. The code takes advantage of the HTML `data` attribute. Basically, by setting `data-id` with the index of the element in a loop, this can be retrieved via the passed in `entry` to the handler as `entry.target.dataset.id`. If you are unfamiliar with the `data` attribute you can read more [here](https://developer.mozilla.org/en-US/docs/Learn/HTML/Howto/Use_data_attributes) about using the `data` attribute.
 
-<doc-example title="Advanced" file="Intersection/Advanced" />
+<doc-example title="Advanced" file="Intersection/Advanced" no-edit />
 
 In the example below, we show multiple cards, but only the visible ones get rendered. The secret is in the wrapper which has `v-intersection` attached to it and a fixed height and width (which acts as a necessary filler when the inner content is not rendered -- so that scrolling won't erratically jump).
 
 > The example below can also be written by using [QIntersection](/vue-components/intersection) component which makes everything even more easy.
 
-<doc-example title="Scrolling Cards" file="Intersection/ScrollingCards" scrollable />
+<doc-example title="Scrolling Cards" file="Intersection/ScrollingCards" scrollable no-edit />
 
 ::: tip
 In the example above we used a Quasar transition. For a full list, please head to [Transitions](/options/transitions) page.
diff --git a/ui/build/build.api.js b/ui/build/build.api.js
@@ -107,13 +107,13 @@ const objectTypes = {
 
   // special type, not common
   Error: {
-    props: [ 'desc' ],
+    props: [ 'desc', 'category', 'examples', 'addedIn' ],
     required: [ 'desc' ]
   },
 
   // special type, not common
   Component: {
-    props: [ 'desc' ],
+    props: [ 'desc', 'category', 'examples', 'addedIn' ],
     required: [ 'desc' ]
   },
 
@@ -124,19 +124,19 @@ const objectTypes = {
 
   // special type, not common
   Element: {
-    props: [ 'desc', 'examples' ],
+    props: [ 'desc', 'category', 'examples', 'addedIn' ],
     required: [ 'desc' ]
   },
 
   // special type, not common
   File: {
-    props: [ 'desc', 'required' ],
+    props: [ 'desc', 'required', 'category', 'examples', 'addedIn' ],
     required: [ 'desc' ]
   },
 
   // special type, not common
   FileList: {
-    props: [ 'desc', 'required' ],
+    props: [ 'desc', 'required', 'category', 'examples', 'addedIn' ],
     required: [ 'desc' ]
   },
 
diff --git a/ui/dev/src/pages/components/intersection-3.vue b/ui/dev/src/pages/components/intersection-3.vue
@@ -5,7 +5,7 @@
       <q-toggle v-model="once" label="Once" />
       <q-select v-model="transition" :options="['', 'fade', 'scale', 'flip-right']" style="min-width: 250px" />
     </div>
-    <table v-if="visible">
+    <table v-if="visible" ref="table">
       <tr
         v-for="index in 10"
         :key="index"
@@ -16,6 +16,7 @@
           :once="once"
           :transition="transition"
           tag="td"
+          :root="tableEl"
           class="int-example-item"
         >
           <q-card class="q-ma-sm">
@@ -44,6 +45,11 @@ export default {
       once: false,
       transition: 'scale'
     }
+  },
+  computed: {
+    tableEl () {
+      return this.$refs.table ? this.$refs.table.$el : null
+    }
   }
 }
 </script>
diff --git a/ui/dev/src/pages/components/intersection-6-iframe.vue b/ui/dev/src/pages/components/intersection-6-iframe.vue
@@ -0,0 +1,11 @@
+<template>
+  <div class="q-pa-md bordered column">
+    QIntersection hosted in an iframe
+    <iframe
+      src="/components/intersection-3"
+      class="rounded-borders q-pa-sm"
+      style="max-width: 800px; width: 100%; height: 400px; border: 1px solid #2196f3"
+    >
+    </iframe>
+  </div>
+</template>
diff --git a/ui/src/components/intersection/QIntersection.js b/ui/src/components/intersection/QIntersection.js
@@ -26,6 +26,10 @@ export default Vue.extend({
 
     margin: String,
     threshold: [ Number, Array ],
+    root: {
+      type: Element,
+      default: null
+    },
 
     disable: Boolean
   },
@@ -42,6 +46,7 @@ export default Vue.extend({
         ? {
           handler: this.__trigger,
           cfg: {
+            root: this.root,
             rootMargin: this.margin,
             threshold: this.threshold
           }
diff --git a/ui/src/components/intersection/QIntersection.json b/ui/src/components/intersection/QIntersection.json
@@ -13,6 +13,7 @@
 
   "props": {
     "tag": {
+      "type": "String",
       "examples": [ "div", "span", "blockquote" ],
       "addedIn": "v1.9.3"
     },
@@ -30,6 +31,14 @@
       "addedIn": "v1.9.5"
     },
 
+    "root": {
+      "type": "Element",
+      "desc": "[Intersection API root prop] Lets you define an alternative to the viewport as your root (through its DOM element); It is important to keep in mind that root needs to be an ancestor of the observed element",
+      "examples": [ "$refs.myTable.$el", "getElementById(\"myTable\")" ],
+      "category": "behavior",
+      "addedIn": "v1.14.1"
+    },
+
     "margin": {
       "type": "String",
       "desc": "[Intersection API rootMargin prop] Allows you to specify the margins for the root, effectively allowing you to either grow or shrink the area used for intersections",
