@gitlab/ui 84.1.0 → 85.0.0

package/src/vendor/bootstrap-vue/src/directives/visible/README.md

@@ -0,0 +1,244 @@
+# Visible
+
+> `v-b-visible` is a lightweight directive that allows you to react when an element becomes visible
+> in the viewport and/or when it moves out of the viewport (or is no longer visible).
+
+## Overview
+
+- `v-b-visible` will call your callback method with a boolean value indicating if the element is
+  visible (intersecting with the viewport) or not.
+- The directive can be placed on almost any element or component.
+- Changes in visibility can also be detected (such as `display: none`), as long as the element is
+  within (or partially within) the viewport, or within the optional offset. Note: transitioning to a
+  non-visible state due to `v-if="false"` _cannot_ be detected.
+- Internally, BootstrapVue uses this directive in several components, such as `<b-img-lazy>`.
+- The `v-b-visible` directive requires browser support of
+  [`IntersectionObserver`](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API).
+  For older browsers that do not support `IntersectionObserver`, you will need to use a
+  [polyfill](/docs/#js).
+- If `IntersectionObserver` support is not detected, then `v-b-visible` will assume the element is
+  _always visible_, and will call the callback once with the argument set to `true`.
+
+## Directive syntax and usage
+
+```html
+<div v-b-visible.[mod1].[mod2]="callback">content</div>
+```
+
+Where `callback` is required:
+
+- A function reference that will be called whenever visibility changes. The callback is passed a
+  single boolean argument. `true` indicates that the element is intersecting (partially or entirely
+  visible) in the viewport, or `false` if the element is not visible/intersecting with the viewport.
+  The callback will be called each time the element's visibility changes (except when the `once`
+  modifier is used. See below for details)
+
+Where `[mod1]` or `[mod2]` can be (all optional):
+
+- A positive integer number representing the offset (margin) in pixels _away_ from the edge of the
+  _viewport_ to determine when the element is considered in (or just about to be in) the viewport.
+  The value adds a margin around the viewport. The default value is `0`.
+- The keyword `once`. When this modifier is present, the callback will be called only once the first
+  time the element is visible (with the argument of `true` indicating the element is
+  intersecting/visible). Note the callback _may be_ called prior to this with an argument of `false`
+  signifying the element is not intersecting/visible.
+
+The order of the modifiers is not important.
+
+### Usage syntax examples
+
+In all use cases, the callback function is required.
+
+#### Basic (no modifiers)
+
+```html
+<template>
+  <div v-b-visible="visibleHandler"> ... </div>
+</template>
+<script>
+export default {
+  methods: {
+    visibleHandler(isVisible) {
+      if (isVisible) {
+        // Do something
+      } else {
+        // Do something else
+      }
+    }
+  }
+}
+</script>
+```
+
+#### With viewport offset modifier
+
+In this example, the modifier value represents 350px (if the element is outside of the physical
+viewport by at least 350px, then it will be considered "visible"):
+
+```html
+<template>
+  <div v-b-visible.350="visibleHandler"> ... </div>
+</template>
+<script>
+export default {
+  methods: {
+    visibleHandler(isVisible) {
+      if (isVisible) {
+        // Do something
+      } else {
+        // Do something else
+      }
+    }
+  }
+}
+</script>
+```
+
+#### With the `once` modifier
+
+```html
+<template>
+  <div v-b-visible.once="visibleHandler"> ... </div>
+</template>
+<script>
+export default {
+  methods: {
+    visibleHandler(isVisible) {
+      if (isVisible) {
+        // This will only ever happen once, when the
+        // element has become visible for the first time
+      } else {
+        // This may happen zero or more times before
+        // the element becomes visible, but will never
+        // happen after the element has become visible
+      }
+    }
+  }
+}
+</script>
+```
+
+#### With both `once` and offset modifiers
+
+```html
+<template>
+  <div v-b-visible.once.350="visibleHandler"> ... </div>
+</template>
+<script>
+export default {
+  methods: {
+    visibleHandler(isVisible) {
+      if (isVisible) {
+        // This will only ever happen once, when the
+        // element is outside of the physical viewport
+        // by at least 350px for the first time
+      } else {
+        // This may happen zero or more times before
+        // the element becomes visible, but will never
+        // happen after the element has become visible
+      }
+    }
+  }
+}
+</script>
+```
+
+## Live examples
+
+Here are two live examples showing two common use cases.
+
+### Visibility of scrolled content
+
+Scroll the container to see the reaction when the `<b-badge>` scrolls into view. Note that
+visibility state will also change if the element is scrolled out of the viewport.
+
+```html
+<template>
+  <div>
+    <div
+      :class="[isVisible ? 'bg-info' : 'bg-light', 'border', 'p-2', 'text-center']"
+      style="height: 85px; overflow-y: scroll;"
+    >
+      <p>{{ text }}</p>
+      <b-badge v-b-visible="handleVisibility">Element with v-b-visible directive</b-badge>
+      <p>{{ text }}</p>
+    </div>
+    <p class="mt-2">
+      Visible: {{ isVisible }}
+    </p>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        isVisible: false,
+        text: `
+          Quis magna Lorem anim amet ipsum do mollit sit cillum voluptate ex nulla
+          tempor. Laborum consequat non elit enim exercitation cillum aliqua
+          consequat id aliqua. Esse ex consectetur mollit voluptate est in duis
+          laboris ad sit ipsum anim Lorem. Incididunt veniam velit elit elit veniam
+          Lorem aliqua quis ullamco deserunt sit enim elit aliqua esse irure. Laborum
+          nisi sit est tempor laborum mollit labore officia laborum excepteur commodo
+          non commodo dolor excepteur commodo. Ipsum fugiat ex est consectetur ipsum
+          commodo tempor sunt in proident. Non elixir food exorcism nacho tequila tasty.
+        `
+      }
+    },
+    methods: {
+      handleVisibility(isVisible) {
+        this.isVisible = isVisible
+      }
+    }
+  }
+</script>
+
+<!-- v-b-visible-scroll.vue -->
+```
+
+One use case for this, when combined with the `once` modifier, is to see if a user has scrolled to
+the bottom of a page or scrollable div (i.e. has "read" the entire terms of service).
+
+### CSS display visibility detection
+
+Click the button to change the `<div>` visibility state. Note that visibility state will also change
+if the element is scrolled out of the viewport.
+
+```html
+<template>
+  <div>
+    <b-button @click="show = !show" class="mb-2">Toggle display</b-button>
+    <p>Visible: {{ isVisible }}</p>
+    <div class="border p-3" style="height: 6em;">
+      <!-- We use Vue's `v-show` directive to control the CSS `display` of the div -->
+      <div v-show="show" class="bg-info p-3">
+        <b-badge v-b-visible="handleVisibility">Element with v-b-visible directive</b-badge>
+      </div>
+    </div>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        show: true,
+        isVisible: false
+      }
+    },
+    methods: {
+      handleVisibility(isVisible) {
+        this.isVisible = isVisible
+      }
+    }
+  }
+</script>
+
+<!-- v-b-visible-display.vue -->
+```
+
+## See also
+
+For more details on `IntersectionObserver`, refer to the
+[MDN documentation](https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API)

package/src/vendor/bootstrap-vue/src/directives/visible/index.d.ts

@@ -0,0 +1,11 @@
+//
+// VBVisible
+//
+import Vue, { DirectiveOptions } from 'vue'
+import { BvPlugin } from '../../'
+
+// Plugin
+export declare const VBVisiblePlugin: BvPlugin
+
+// Directive: v-b-visible
+export declare const VBVisible: DirectiveOptions

package/src/vendor/bootstrap-vue/src/directives/visible/index.js

@@ -0,0 +1,8 @@
+import { VBVisible } from './visible'
+import { pluginFactory } from '../../utils/plugins'
+
+const VBVisiblePlugin = /*#__PURE__*/ pluginFactory({
+  directives: { VBVisible }
+})
+
+export { VBVisiblePlugin, VBVisible }

package/src/vendor/bootstrap-vue/src/directives/visible/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@bootstrap-vue/v-b-visible",
+  "version": "0.0.0",
+  "meta": {
+    "title": "Visible",
+    "description": "The `v-b-visible` directive allows you to react when an element becomes visible in the viewport.",
+    "directive": "VBVisible",
+    "version": "2.1.0",
+    "expression": [
+      "Function"
+    ],
+    "modifiers": [
+      {
+        "name": "once",
+        "description": "Only calls the callback once when the element becomes visible in the viewport"
+      },
+      {
+        "name": "{###}",
+        "pattern": "[0-9]+",
+        "description": "An offset value in pixels (where `{###}` is the number of pixels) relative to the viewport, defaults to 0. Negative values allowed"
+      }
+    ]
+  }
+}

package/src/vendor/bootstrap-vue/src/directives/visible/visible.js

@@ -0,0 +1,184 @@
+// v-b-visible
+// Private visibility check directive
+// Based on IntersectionObserver
+//
+// Usage:
+//  v-b-visibility.<margin>.<once>="<callback>"
+//
+//  Value:
+//  <callback>: method to be called when visibility state changes, receives one arg:
+//     true:  element is visible
+//     false: element is not visible
+//     null:  IntersectionObserver not supported
+//
+//  Modifiers:
+//    <margin>: a positive decimal value of pixels away from viewport edge
+//              before being considered "visible". default is 0
+//    <once>:   keyword 'once', meaning when the element becomes visible and
+//              callback is called observation/notification will stop.
+//
+// When used in a render function:
+// export default {
+//   directives: { 'b-visible': VBVisible },
+//   render(h) {
+//     h(
+//       'div',
+//       {
+//         directives: [
+//           { name: 'b-visible', value=this.callback, modifiers: { '123':true, 'once':true } }
+//         ]
+//       }
+//     )
+//   }
+
+import { RX_DIGITS } from '../../constants/regex'
+import { requestAF } from '../../utils/dom'
+import { isFunction } from '../../utils/inspect'
+import { looseEqual } from '../../utils/loose-equal'
+import { clone, keys } from '../../utils/object'
+import { nextTick } from '../../vue'
+
+const OBSERVER_PROP_NAME = '__bv__visibility_observer'
+
+class VisibilityObserver {
+  constructor(el, options) {
+    this.el = el
+    this.callback = options.callback
+    this.margin = options.margin || 0
+    this.once = options.once || false
+    this.observer = null
+    this.visible = undefined
+    this.doneOnce = false
+    // Create the observer instance (if possible)
+    this.createObserver()
+  }
+
+  createObserver() {
+    // Remove any previous observer
+    if (this.observer) {
+      /* istanbul ignore next */
+      this.stop()
+    }
+
+    // Should only be called once and `callback` prop should be a function
+    if (this.doneOnce || !isFunction(this.callback)) {
+      /* istanbul ignore next */
+      return
+    }
+
+    // Create the observer instance
+    try {
+      // Future: Possibly add in other modifiers for left/right/top/bottom
+      // offsets, root element reference, and thresholds
+      this.observer = new IntersectionObserver(this.handler.bind(this), {
+        // `null` = 'viewport'
+        root: null,
+        // Pixels away from view port to consider "visible"
+        rootMargin: this.margin,
+        // Intersection ratio of el and root (as a value from 0 to 1)
+        threshold: 0
+      })
+    } catch {
+      // No IntersectionObserver support, so just stop trying to observe
+      this.doneOnce = true
+      this.observer = undefined
+      this.callback(null)
+      return
+    }
+
+    // Start observing in a `$nextTick()` (to allow DOM to complete rendering)
+    /* istanbul ignore next: IntersectionObserver not supported in JSDOM */
+    nextTick(() => {
+      requestAF(() => {
+        // Placed in an `if` just in case we were destroyed before
+        // this `requestAnimationFrame` runs
+        if (this.observer) {
+          this.observer.observe(this.el)
+        }
+      })
+    })
+  }
+
+  /* istanbul ignore next */
+  handler(entries) {
+    const entry = entries ? entries[0] : {}
+    const isIntersecting = Boolean(entry.isIntersecting || entry.intersectionRatio > 0.0)
+    if (isIntersecting !== this.visible) {
+      this.visible = isIntersecting
+      this.callback(isIntersecting)
+      if (this.once && this.visible) {
+        this.doneOnce = true
+        this.stop()
+      }
+    }
+  }
+
+  stop() {
+    /* istanbul ignore next */
+    this.observer && this.observer.disconnect()
+    this.observer = null
+  }
+}
+
+const destroy = el => {
+  const observer = el[OBSERVER_PROP_NAME]
+  if (observer && observer.stop) {
+    observer.stop()
+  }
+  delete el[OBSERVER_PROP_NAME]
+}
+
+const bind = (el, { value, modifiers }) => {
+  // `value` is the callback function
+  const options = {
+    margin: '0px',
+    once: false,
+    callback: value
+  }
+  // Parse modifiers
+  keys(modifiers).forEach(mod => {
+    /* istanbul ignore else: Until <b-img-lazy> is switched to use this directive */
+    if (RX_DIGITS.test(mod)) {
+      options.margin = `${mod}px`
+    } else if (mod.toLowerCase() === 'once') {
+      options.once = true
+    }
+  })
+  // Destroy any previous observer
+  destroy(el)
+  // Create new observer
+  el[OBSERVER_PROP_NAME] = new VisibilityObserver(el, options)
+  // Store the current modifiers on the object (cloned)
+  el[OBSERVER_PROP_NAME]._prevModifiers = clone(modifiers)
+}
+
+// When the directive options may have been updated (or element)
+const componentUpdated = (el, { value, oldValue, modifiers }, vnode) => {
+  // Compare value/oldValue and modifiers to see if anything has changed
+  // and if so, destroy old observer and create new observer
+  /* istanbul ignore next */
+  modifiers = clone(modifiers)
+  /* istanbul ignore next */
+  if (
+    el &&
+    (value !== oldValue ||
+      !el[OBSERVER_PROP_NAME] ||
+      !looseEqual(modifiers, el[OBSERVER_PROP_NAME]._prevModifiers))
+  ) {
+    // Re-bind on element
+    bind(el, { value, modifiers }, vnode)
+  }
+}
+
+// When directive un-binds from element
+const unbind = el => {
+  // Remove the observer
+  destroy(el)
+}
+
+// Export the directive
+export const VBVisible = {
+  bind,
+  componentUpdated,
+  unbind
+}