@gitlab/ui 84.2.0 → 85.0.0

package/src/vendor/bootstrap-vue/src/components/alert/README.md

@@ -0,0 +1,280 @@
+# Alert
+
+> Provide contextual feedback messages for typical user actions with the handful of available and
+> flexible alert messages.
+
+## Overview
+
+Alerts are available for any length of text, as well as an optional dismiss button (and optional
+auto-dismissing).
+
+```html
+<template>
+  <div>
+    <b-alert show>Default Alert</b-alert>
+
+    <b-alert variant="success" show>Success Alert</b-alert>
+
+    <b-alert v-model="showDismissibleAlert" variant="danger" dismissible>
+      Dismissible Alert!
+    </b-alert>
+
+    <b-alert
+      :show="dismissCountDown"
+      dismissible
+      variant="warning"
+      @dismissed="dismissCountDown=0"
+      @dismiss-count-down="countDownChanged"
+    >
+      <p>This alert will dismiss after {{ dismissCountDown }} seconds...</p>
+      <b-progress
+        variant="warning"
+        :max="dismissSecs"
+        :value="dismissCountDown"
+        height="4px"
+      ></b-progress>
+    </b-alert>
+
+    <b-button @click="showAlert" variant="info" class="m-1">
+      Show alert with count-down timer
+    </b-button>
+    <b-button @click="showDismissibleAlert=true" variant="info" class="m-1">
+      Show dismissible alert ({{ showDismissibleAlert ? 'visible' : 'hidden' }})
+    </b-button>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        dismissSecs: 10,
+        dismissCountDown: 0,
+        showDismissibleAlert: false
+      }
+    },
+    methods: {
+      countDownChanged(dismissCountDown) {
+        this.dismissCountDown = dismissCountDown
+      },
+      showAlert() {
+        this.dismissCountDown = this.dismissSecs
+      }
+    }
+  }
+</script>
+
+<!-- b-alert.vue -->
+```
+
+## Visible state
+
+Use the `show` prop to control the visibility state of the alert. By default alerts are **not**
+shown. Set the prop `show` to explicitly display them.
+
+The `show` prop accepts boolean `true` or `false` to show and hide the alert respectively. It can
+also be set to a positive integer (representing seconds) to create a self dismissing alert. See the
+[Auto Dismissing Alerts](#auto-dismissing-alerts) section below for details.
+
+### `v-model` support
+
+You can use the `v-model` directive to create two-way data bindings on the `show` prop as in
+`v-model="showDismissibleAlert"` above. Useful when you use dismissible because when user closes the
+alert, your variable will be updated. Do not use the `show` prop when using `v-model`.
+
+## Contextual variants
+
+For proper styling of `<b-alert>`, use one of the four required contextual variants by setting the
+`variant` prop to one of the following: `info`, `success`, `warning` or `danger`. The default is
+`info`.
+
+```html
+<div>
+  <b-alert show variant="primary">Primary Alert</b-alert>
+  <b-alert show variant="secondary">Secondary Alert</b-alert>
+  <b-alert show variant="success">Success Alert</b-alert>
+  <b-alert show variant="danger">Danger Alert</b-alert>
+  <b-alert show variant="warning">Warning Alert</b-alert>
+  <b-alert show variant="info">Info Alert</b-alert>
+  <b-alert show variant="light">Light Alert</b-alert>
+  <b-alert show variant="dark">Dark Alert</b-alert>
+</div>
+
+<!-- b-alert-variants.vue -->
+```
+
+### Conveying meaning to assistive technologies
+
+Using color variants to add meaning only provides a visual indication, which will not be conveyed to
+users of assistive technologies – such as screen readers. Ensure that information denoted by the
+color is either obvious from the content itself (e.g. the visible text), or is included through
+alternative means, such as additional text hidden with the `.sr-only` class.
+
+## Additional content inside alerts
+
+`<b-alerts>` can also contain additional HTML elements like headings and paragraphs, which will be
+styled with the appropriate color matching the variant.
+
+```html
+<div>
+  <b-alert show variant="success">
+    <h4 class="alert-heading">Well done!</h4>
+    <p>
+      Aww yeah, you successfully read this important alert message. This example text is going to
+      run a bit longer so that you can see how spacing within an alert works with this kind of
+      content.
+    </p>
+    <hr>
+    <p class="mb-0">
+      Whenever you need to, be sure to use margin utilities to keep things nice and tidy.
+    </p>
+  </b-alert>
+</div>
+
+<!-- b-alert-content.vue -->
+```
+
+### Color of links within alerts
+
+Use the `.alert-link` utility CSS class to quickly provide matching colored links within any alert.
+Use on `<a>` or `<b-link>`.
+
+```html
+<div>
+  <b-alert show variant="primary"><a href="#" class="alert-link">Primary Alert</a></b-alert>
+  <b-alert show variant="secondary"><a href="#" class="alert-link">Secondary Alert</a></b-alert>
+  <b-alert show variant="success"><a href="#" class="alert-link">Success Alert</a></b-alert>
+  <b-alert show variant="danger"><a href="#" class="alert-link">Danger Alert</a></b-alert>
+  <b-alert show variant="warning"><a href="#" class="alert-link">Warning Alert</a></b-alert>
+  <b-alert show variant="info"><a href="#" class="alert-link">Info Alert</a></b-alert>
+  <b-alert show variant="light"><a href="#" class="alert-link">Light Alert</a></b-alert>
+  <b-alert show variant="dark"><a href="#" class="alert-link">Dark Alert</a></b-alert>
+</div>
+
+<!-- b-alert-links.vue -->
+```
+
+## Dismissible alerts
+
+Using the `dismissible` prop it's possible to dismiss any `<b-alert>` inline. This will add a close
+`X` button. Use the `dismiss-label` prop to change the hidden label text associated with the dismiss
+button.
+
+```html
+<div>
+  <b-alert show dismissible>
+    Dismissible Alert! Click the close button over there <b>&rArr;</b>
+  </b-alert>
+</div>
+
+<!-- b-alert-dismiss.vue -->
+```
+
+### Auto dismissing alerts
+
+To create a `<b-alert>` that dismisses automatically after a period of time, set the `show` prop (or
+the `v-model`) to the number of seconds you would like the `<b-alert>` to remain visible for. Only
+integer number of seconds are supported.
+
+```html
+<template>
+  <div>
+    <b-alert
+      :show="dismissCountDown"
+      dismissible
+      variant="warning"
+      @dismissed="dismissCountDown=0"
+      @dismiss-count-down="countDownChanged"
+    >
+      This alert will dismiss after {{ dismissCountDown }} seconds...
+    </b-alert>
+    <b-button @click="showAlert" variant="info" class="m-1">
+      Show alert with count-down timer
+    </b-button>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        dismissSecs: 5,
+        dismissCountDown: 0
+      }
+    },
+    methods: {
+      countDownChanged(dismissCountDown) {
+        this.dismissCountDown = dismissCountDown
+      },
+      showAlert() {
+        this.dismissCountDown = this.dismissSecs
+      }
+    }
+  }
+</script>
+
+<!-- b-alert-auto-dismissing.vue -->
+```
+
+## Fading alerts
+
+Use the `fade` prop to enable animation. By default alerts are not animated.
+
+```html
+<template>
+  <div>
+    <b-alert show dismissible fade>Dismissible Alert!</b-alert>
+
+    <b-alert
+      variant="danger"
+      dismissible
+      fade
+      :show="showDismissibleAlert"
+      @dismissed="showDismissibleAlert=false"
+    >
+      Dismissible Alert!
+    </b-alert>
+
+    <b-alert
+      :show="dismissCountDown"
+      dismissible
+      fade
+      variant="warning"
+      @dismiss-count-down="countDownChanged"
+    >
+      This alert will dismiss after {{ dismissCountDown }} seconds...
+    </b-alert>
+
+    <b-button @click="showAlert" variant="info" class="m-1">
+      Show alert with count-down timer
+    </b-button>
+    <b-button @click="showDismissibleAlert=true" variant="info" class="m-1">
+      Show dismissible alert ({{ showDismissibleAlert ? 'visible' : 'hidden' }})
+    </b-button>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        dismissSecs: 5,
+        dismissCountDown: 0,
+        showDismissibleAlert: false
+      }
+    },
+    methods: {
+      countDownChanged(dismissCountDown) {
+        this.dismissCountDown = dismissCountDown
+      },
+      showAlert() {
+        this.dismissCountDown = this.dismissSecs
+      }
+    }
+  }
+</script>
+
+<!-- b-alert-fade.vue -->
+```
+
+<!-- Component reference added automatically from component package.json -->

package/src/vendor/bootstrap-vue/src/components/alert/alert.js

@@ -0,0 +1,185 @@
+import { NAME_ALERT } from '../../constants/components'
+import { EVENT_NAME_DISMISSED, EVENT_NAME_DISMISS_COUNT_DOWN } from '../../constants/events'
+import {
+  PROP_TYPE_BOOLEAN,
+  PROP_TYPE_BOOLEAN_NUMBER_STRING,
+  PROP_TYPE_STRING
+} from '../../constants/props'
+import { SLOT_NAME_DISMISS } from '../../constants/slots'
+import { normalizeSlotMixin } from '../../mixins/normalize-slot'
+import { requestAF } from '../../utils/dom'
+import { isBoolean, isNumeric } from '../../utils/inspect'
+import { makeModelMixin } from '../../utils/model'
+import { toInteger } from '../../utils/number'
+import { sortKeys } from '../../utils/object'
+import { makeProp, makePropsConfigurable } from '../../utils/props'
+import { COMPONENT_UID_KEY, extend } from '../../vue'
+import { BButtonClose } from '../button/button-close'
+import { BVTransition } from '../transition/bv-transition'
+
+// --- Constants ---
+
+const {
+  mixin: modelMixin,
+  props: modelProps,
+  prop: MODEL_PROP_NAME,
+  event: MODEL_EVENT_NAME
+} = makeModelMixin('show', {
+  type: PROP_TYPE_BOOLEAN_NUMBER_STRING,
+  defaultValue: false
+})
+
+// --- Helper methods ---
+
+// Convert `show` value to a number
+const parseCountDown = show => {
+  if (show === '' || isBoolean(show)) {
+    return 0
+  }
+  show = toInteger(show, 0)
+  return show > 0 ? show : 0
+}
+
+// Convert `show` value to a boolean
+const parseShow = show => {
+  if (show === '' || show === true) {
+    return true
+  }
+  if (toInteger(show, 0) < 1) {
+    // Boolean will always return false for the above comparison
+    return false
+  }
+  return !!show
+}
+
+// --- Props ---
+
+export const props = makePropsConfigurable(
+  sortKeys({
+    ...modelProps,
+    dismissLabel: makeProp(PROP_TYPE_STRING, 'Close'),
+    dismissible: makeProp(PROP_TYPE_BOOLEAN, false),
+    fade: makeProp(PROP_TYPE_BOOLEAN, false),
+    variant: makeProp(PROP_TYPE_STRING, 'info')
+  }),
+  NAME_ALERT
+)
+
+// --- Main component ---
+
+// @vue/component
+export const BAlert = /*#__PURE__*/ extend({
+  name: NAME_ALERT,
+  mixins: [modelMixin, normalizeSlotMixin],
+  props,
+  data() {
+    return {
+      countDown: 0,
+      // If initially shown, we need to set these for SSR
+      localShow: parseShow(this[MODEL_PROP_NAME])
+    }
+  },
+  watch: {
+    [MODEL_PROP_NAME](newValue) {
+      this.countDown = parseCountDown(newValue)
+      this.localShow = parseShow(newValue)
+    },
+    countDown(newValue) {
+      this.clearCountDownInterval()
+      const show = this[MODEL_PROP_NAME]
+      // Ignore if `show` transitions to a boolean value
+      if (isNumeric(show)) {
+        this.$emit(EVENT_NAME_DISMISS_COUNT_DOWN, newValue)
+        // Update the v-model if needed
+        if (show !== newValue) {
+          this.$emit(MODEL_EVENT_NAME, newValue)
+        }
+        if (newValue > 0) {
+          this.localShow = true
+          this.$_countDownTimeout = setTimeout(() => {
+            this.countDown--
+          }, 1000)
+        } else {
+          // Slightly delay the hide to allow any UI updates
+          this.$nextTick(() => {
+            requestAF(() => {
+              this.localShow = false
+            })
+          })
+        }
+      }
+    },
+    localShow(newValue) {
+      const show = this[MODEL_PROP_NAME]
+      // Only emit dismissed events for dismissible or auto-dismissing alerts
+      if (!newValue && (this.dismissible || isNumeric(show))) {
+        this.$emit(EVENT_NAME_DISMISSED)
+      }
+      // Only emit booleans if we weren't passed a number via v-model
+      if (!isNumeric(show) && show !== newValue) {
+        this.$emit(MODEL_EVENT_NAME, newValue)
+      }
+    }
+  },
+  created() {
+    // Create private non-reactive props
+    this.$_filterTimer = null
+
+    const show = this[MODEL_PROP_NAME]
+    this.countDown = parseCountDown(show)
+    this.localShow = parseShow(show)
+  },
+  beforeDestroy() {
+    this.clearCountDownInterval()
+  },
+  methods: {
+    dismiss() {
+      this.clearCountDownInterval()
+      this.countDown = 0
+      this.localShow = false
+    },
+    clearCountDownInterval() {
+      clearTimeout(this.$_countDownTimeout)
+      this.$_countDownTimeout = null
+    }
+  },
+  render(h) {
+    let $alert = h()
+    if (this.localShow) {
+      const { dismissible, variant } = this
+
+      let $dismissButton = h()
+      if (dismissible) {
+        // Add dismiss button
+        $dismissButton = h(
+          BButtonClose,
+          {
+            attrs: { 'aria-label': this.dismissLabel },
+            on: { click: this.dismiss }
+          },
+          [this.normalizeSlot(SLOT_NAME_DISMISS)]
+        )
+      }
+
+      $alert = h(
+        'div',
+        {
+          staticClass: 'alert',
+          class: {
+            'alert-dismissible': dismissible,
+            [`alert-${variant}`]: variant
+          },
+          attrs: {
+            role: 'alert',
+            'aria-live': 'polite',
+            'aria-atomic': true
+          },
+          key: this[COMPONENT_UID_KEY]
+        },
+        [$dismissButton, this.normalizeSlot()]
+      )
+    }
+
+    return h(BVTransition, { props: { noFade: !this.fade } }, [$alert])
+  }
+})