@gitlab/ui 84.2.0 → 85.0.0

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

@@ -0,0 +1,164 @@
+# Toggle
+
+> `v-b-toggle` is a light-weight directive for toggling the visibility of collapses and sidebars,
+> and includes automated [WAI-ARIA accessibility](/docs/reference/accessibility) attribute handling.
+
+## Overview
+
+The `v-b-toggle` directive can be used on interactive elements, such as buttons, to toggle the
+visibility state of the [`<b-collapse>`](/docs/components/collapse) and
+[`<b-sidebar>`](/docs/components/sidebar) components.
+
+Besides toggling the visibility of the target component, the directive automatically updates ARIA
+accessibility attributes on the element it is applied to so that they reflect the visibility state
+of the target component. Refer to the [Accessibility section](#accessibility) below for additional
+details and caveats.
+
+## Directive syntax and usage
+
+The directive is applied to the element or component that triggers the visibility of the target. The
+target component can be specified (via its ID) as either a directive modifier(s), the directive
+argument, or as a string/array passed to as the directive value:
+
+- `v-b-toggle.my-collapse` - the directive modifier (multiple targets allowed, each modifier is a
+  target ID)
+- `v-b-toggle:my-collapse` - the directive argument
+  ([Vue dynamic argument](https://vuejs.org/v2/guide/syntax.html#Dynamic-Arguments) is supported)
+  <span class="badge badge-info small" aria-label="Available in BootstrapVue v2.14.0+">v2.14.0+</span>
+- `v-b-toggle="'my-collapse'"` - the directive value as a string ID
+- `v-b-toggle="'my-collapse1 my-collapse2'"` - the directive value as a space separated string of
+  IDs
+  <span class="badge badge-info small" aria-label="Available in BootstrapVue v2.14.0+">v2.14.0+</span>
+- `v-b-toggle="['my-collapse1', 'my-collapse2']"` - the directive value as an array of string IDs
+  <span class="badge badge-info small" aria-label="Available in BootstrapVue v2.14.0+">v2.14.0+</span>
+
+Modifiers, argument, and the value can be used at the same time when targeting multiple components.
+
+**Example usage:**
+
+```html
+<template>
+  <div>
+    <div class="mb-3">
+      <b-button v-b-toggle.my-collapse>Toggle Collapse</b-button>
+      <b-button v-b-toggle.my-sidebar>Toggle Sidebar</b-button>
+    </div>
+
+    <b-collapse id="my-collapse">
+      <b-card title="Collapsible card">
+        Hello world!
+      </b-card>
+    </b-collapse>
+
+    <b-sidebar id="my-sidebar" title="Sidebar" shadow>
+      <div class="px-3 py-2">
+        Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis
+        in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
+      </div>
+    </b-sidebar>
+  </div>
+</template>
+
+<!-- v-b-toggle-directive.vue -->
+```
+
+## Usage on links
+
+<span class="badge badge-info small">2.15.0+</span>
+
+If placing the directive on a link (or a component that renders a link), the target ID can
+alternatively be specified via the `href` attribute.
+
+Note that the browser URL will change and the page may scroll the target into view. To prevent the
+URL from changing and the page from scrolling, add `@click.prevent` to the link.
+
+**Example usage:**
+
+```html
+<template>
+  <div>
+    <div class="mb-3">
+      <a v-b-toggle href="#example-collapse" @click.prevent>Toggle Collapse</a>
+      <b-button v-b-toggle href="#example-sidebar" @click.prevent>Toggle Sidebar</b-button>
+    </div>
+
+    <b-collapse id="example-collapse">
+      <b-card title="Collapsible card">
+        Hello world!
+      </b-card>
+    </b-collapse>
+
+    <b-sidebar id="example-sidebar" title="Sidebar" shadow>
+      <div class="px-3 py-2">
+        Cras mattis consectetur purus sit amet fermentum. Cras justo odio, dapibus ac facilisis
+        in, egestas eget quam. Morbi leo risus, porta ac consectetur ac, vestibulum at eros.
+      </div>
+    </b-sidebar>
+  </div>
+</template>
+
+<!-- v-b-toggle-links.vue -->
+```
+
+## Hiding and showing content in the toggle trigger element
+
+When using the `v-b-toggle` directive, the class `collapsed` will automatically be placed on the
+trigger element when the target component is closed, and removed when open. As of BootstrapVue
+`2.14.0`, the class `not-collapsed` will be applied when the target is _not_ closed.
+
+**Example HTML markup:**
+
+```html
+<div>
+  <b-button v-b-toggle:my-collapse>
+    <span class="when-open">Close</span><span class="when-closed">Open</span> My Collapse
+  </b-button>
+  <b-collapse id="my-collapse">
+    <!-- Content here -->
+  </b-collapse>
+</div>
+```
+
+**Example Custom CSS:**
+
+```css
+.collapsed > .when-open,
+.not-collapsed > .when-closed {
+  display: none;
+}
+```
+
+## Preventing the target from opening or closing
+
+To prevent the trigger element from toggling the target, set the `disabled` prop on `<button>`,
+`<b-button>`, or `<b-link>` (or components based on from `<b-link>`) and the toggle event will _not_
+dispatched to the target(s).
+
+## Accessibility
+
+The directive, for accessibility reasons, should be placed on an clickable interactive element such
+as a `<button>` or `<b-button>`, which can easily be accessed by keyboard-only users and screen
+reader users. Elements that do not natively have an accessibility role of `button` (or `link`) will
+have the attributes `role="button"` and `tabindex="0"` applied, and will have the appropriate click
+handler instantiated. Therefore it is _highly recommended_ to _not_ place the directive on form
+controls other than buttons.
+
+The directive applies, and dynamically updates, the following ARIA attributes on the trigger
+element:
+
+- `aria-controls` - the ID(s) of the collapse or sidebar component(s) being toggled
+- `aria-expanded` - the visibility state of the collapse or sidebar (see the
+  [caveats section](#caveats-with-multiple-targets) below)
+
+### Caveats with multiple targets
+
+When multiple targets are specified, the value of the `aria-expanded` attribute may not be correct
+if the individual target components can have their collapsed state controlled independently (either
+via `v-model`, other controls with `v-b-toggle` directive, or CSS visibility).
+
+## See also
+
+- [`<b-collapse>`](/docs/components/collapse) Collapsible content with accordion support
+- [`<b-sidebar>`](/docs/components/sidebar) Off-canvas sidebar
+- [`<b-navbar-toggle>`](/docs/components/navbar#b-navbar-toggle-and-b-collapse-is-nav) Navbar
+  hamburger toggle button (based on `v-b-toggle` directive)

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

@@ -0,0 +1,11 @@
+//
+// VBToggle
+//
+import Vue, { DirectiveOptions } from 'vue'
+import { BvPlugin } from '../../'
+
+// Plugin
+export declare const VBTogglePlugin: BvPlugin
+
+// directive: v-b-toggle
+export declare const VBToggle: DirectiveOptions

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

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

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

@@ -0,0 +1,26 @@
+{
+  "name": "@bootstrap-vue/v-b-toggle",
+  "version": "1.0.0",
+  "meta": {
+    "title": "Toggle",
+    "description": "A light-weight directive for toggling visibility state for collapses and sidebars by ID. It automatically handles the accessibility attributes on the trigger element.",
+    "directive": "VBToggle",
+    "expression": [
+      "String",
+      "Array"
+    ],
+    "arg": {
+      "version": "2.14.0",
+      "pattern": "[a-zA-Z][a-zA-Z0-9_\\-]*",
+      "description": "ID of component to toggle",
+      "required": false
+    },
+    "modifiers": [
+      {
+        "name": "{componentId}",
+        "pattern": "[a-zA-Z][a-zA-Z0-9_\\-]*",
+        "description": "ID of component to toggle"
+      }
+    ]
+  }
+}

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

@@ -0,0 +1,274 @@
+import { NAME_COLLAPSE } from '../../constants/components'
+import { IS_BROWSER } from '../../constants/env'
+import { EVENT_OPTIONS_PASSIVE } from '../../constants/events'
+import { CODE_ENTER, CODE_SPACE } from '../../constants/key-codes'
+import { RX_HASH, RX_HASH_ID, RX_SPACE_SPLIT } from '../../constants/regex'
+import { arrayIncludes, concat } from '../../utils/array'
+import { getInstanceFromDirective } from '../../utils/get-instance-from-directive'
+import {
+  addClass,
+  getAttr,
+  hasAttr,
+  isDisabled,
+  isTag,
+  removeAttr,
+  removeClass,
+  removeStyle,
+  requestAF,
+  setAttr,
+  setStyle
+} from '../../utils/dom'
+import { getRootActionEventName, getRootEventName, eventOn, eventOff } from '../../utils/events'
+import { isString } from '../../utils/inspect'
+import { looseEqual } from '../../utils/loose-equal'
+import { keys } from '../../utils/object'
+import { getEventRoot } from '../../utils/get-event-root'
+
+// --- Constants ---
+
+// Classes to apply to trigger element
+const CLASS_BV_TOGGLE_COLLAPSED = 'collapsed'
+const CLASS_BV_TOGGLE_NOT_COLLAPSED = 'not-collapsed'
+
+// Property key for handler storage
+const BV_BASE = '__BV_toggle'
+// Root event listener property (Function)
+const BV_TOGGLE_ROOT_HANDLER = `${BV_BASE}_HANDLER__`
+// Trigger element click handler property (Function)
+const BV_TOGGLE_CLICK_HANDLER = `${BV_BASE}_CLICK__`
+// Target visibility state property (Boolean)
+const BV_TOGGLE_STATE = `${BV_BASE}_STATE__`
+// Target ID list property (Array)
+const BV_TOGGLE_TARGETS = `${BV_BASE}_TARGETS__`
+
+// Commonly used strings
+const STRING_FALSE = 'false'
+const STRING_TRUE = 'true'
+
+// Commonly used attribute names
+const ATTR_ARIA_CONTROLS = 'aria-controls'
+const ATTR_ARIA_EXPANDED = 'aria-expanded'
+const ATTR_ROLE = 'role'
+const ATTR_TABINDEX = 'tabindex'
+
+// Commonly used style properties
+const STYLE_OVERFLOW_ANCHOR = 'overflow-anchor'
+
+// Emitted control event for collapse (emitted to collapse)
+const ROOT_ACTION_EVENT_NAME_TOGGLE = getRootActionEventName(NAME_COLLAPSE, 'toggle')
+
+// Listen to event for toggle state update (emitted by collapse)
+const ROOT_EVENT_NAME_STATE = getRootEventName(NAME_COLLAPSE, 'state')
+
+// Private event emitted on `$root` to ensure the toggle state is always synced
+// Gets emitted even if the state of b-collapse has not changed
+// This event is NOT to be documented as people should not be using it
+const ROOT_EVENT_NAME_SYNC_STATE = getRootEventName(NAME_COLLAPSE, 'sync-state')
+
+// Private event we send to collapse to request state update sync event
+const ROOT_ACTION_EVENT_NAME_REQUEST_STATE = getRootActionEventName(NAME_COLLAPSE, 'request-state')
+
+const KEYDOWN_KEY_CODES = [CODE_ENTER, CODE_SPACE]
+
+// --- Helper methods ---
+
+const isNonStandardTag = el => !arrayIncludes(['button', 'a'], el.tagName.toLowerCase())
+
+const getTargets = ({ modifiers, arg, value }, el) => {
+  // Any modifiers are considered target IDs
+  const targets = keys(modifiers || {})
+
+  // If value is a string, split out individual targets (if space delimited)
+  value = isString(value) ? value.split(RX_SPACE_SPLIT) : value
+
+  // Support target ID as link href (`href="#id"`)
+  if (isTag(el.tagName, 'a')) {
+    const href = getAttr(el, 'href') || ''
+    if (RX_HASH_ID.test(href)) {
+      targets.push(href.replace(RX_HASH, ''))
+    }
+  }
+
+  // Add ID from `arg` (if provided), and support value
+  // as a single string ID or an array of string IDs
+  // If `value` is not an array or string, then it gets filtered out
+  concat(arg, value).forEach(t => isString(t) && targets.push(t))
+
+  // Return only unique and truthy target IDs
+  return targets.filter((t, index, arr) => t && arr.indexOf(t) === index)
+}
+
+const removeClickListener = el => {
+  const handler = el[BV_TOGGLE_CLICK_HANDLER]
+  if (handler) {
+    eventOff(el, 'click', handler, EVENT_OPTIONS_PASSIVE)
+    eventOff(el, 'keydown', handler, EVENT_OPTIONS_PASSIVE)
+  }
+  el[BV_TOGGLE_CLICK_HANDLER] = null
+}
+
+const addClickListener = (el, instance) => {
+  removeClickListener(el)
+  if (instance) {
+    const handler = event => {
+      if (
+        !(event.type === 'keydown' && !arrayIncludes(KEYDOWN_KEY_CODES, event.keyCode)) &&
+        !isDisabled(el)
+      ) {
+        const targets = el[BV_TOGGLE_TARGETS] || []
+        targets.forEach(target => {
+          getEventRoot(instance).$emit(ROOT_ACTION_EVENT_NAME_TOGGLE, target)
+        })
+      }
+    }
+    el[BV_TOGGLE_CLICK_HANDLER] = handler
+    eventOn(el, 'click', handler, EVENT_OPTIONS_PASSIVE)
+    if (isNonStandardTag(el)) {
+      eventOn(el, 'keydown', handler, EVENT_OPTIONS_PASSIVE)
+    }
+  }
+}
+
+const removeRootListeners = (el, instance) => {
+  if (el[BV_TOGGLE_ROOT_HANDLER] && instance) {
+    getEventRoot(instance).$off(
+      [ROOT_EVENT_NAME_STATE, ROOT_EVENT_NAME_SYNC_STATE],
+      el[BV_TOGGLE_ROOT_HANDLER]
+    )
+  }
+  el[BV_TOGGLE_ROOT_HANDLER] = null
+}
+
+const addRootListeners = (el, instance) => {
+  removeRootListeners(el, instance)
+  if (instance) {
+    const handler = (id, state) => {
+      // `state` will be `true` if target is expanded
+      if (arrayIncludes(el[BV_TOGGLE_TARGETS] || [], id)) {
+        // Set/Clear 'collapsed' visibility class state
+        el[BV_TOGGLE_STATE] = state
+        // Set `aria-expanded` and class state on trigger element
+        setToggleState(el, state)
+      }
+    }
+    el[BV_TOGGLE_ROOT_HANDLER] = handler
+    // Listen for toggle state changes (public) and sync (private)
+    getEventRoot(instance).$on([ROOT_EVENT_NAME_STATE, ROOT_EVENT_NAME_SYNC_STATE], handler)
+  }
+}
+
+const setToggleState = (el, state) => {
+  // State refers to the visibility of the collapse/sidebar
+  if (state) {
+    removeClass(el, CLASS_BV_TOGGLE_COLLAPSED)
+    addClass(el, CLASS_BV_TOGGLE_NOT_COLLAPSED)
+    setAttr(el, ATTR_ARIA_EXPANDED, STRING_TRUE)
+  } else {
+    removeClass(el, CLASS_BV_TOGGLE_NOT_COLLAPSED)
+    addClass(el, CLASS_BV_TOGGLE_COLLAPSED)
+    setAttr(el, ATTR_ARIA_EXPANDED, STRING_FALSE)
+  }
+}
+
+// Reset and remove a property from the provided element
+const resetProp = (el, prop) => {
+  el[prop] = null
+  delete el[prop]
+}
+
+// Handle directive updates
+const handleUpdate = (el, binding, vnode) => {
+  /* istanbul ignore next: should never happen */
+  if (!IS_BROWSER || !getInstanceFromDirective(vnode, binding)) {
+    return
+  }
+
+  // If element is not a button or link, we add `role="button"`
+  // and `tabindex="0"` for accessibility reasons
+  if (isNonStandardTag(el)) {
+    if (!hasAttr(el, ATTR_ROLE)) {
+      setAttr(el, ATTR_ROLE, 'button')
+    }
+    if (!hasAttr(el, ATTR_TABINDEX)) {
+      setAttr(el, ATTR_TABINDEX, '0')
+    }
+  }
+
+  // Ensure the collapse class and `aria-*` attributes persist
+  // after element is updated (either by parent re-rendering
+  // or changes to this element or its contents)
+  setToggleState(el, el[BV_TOGGLE_STATE])
+
+  // Parse list of target IDs
+  const targets = getTargets(binding, el)
+
+  // Ensure the `aria-controls` hasn't been overwritten
+  // or removed when vnode updates
+  // Also ensure to set `overflow-anchor` to `none` to prevent
+  // the browser's scroll anchoring behavior
+  /* istanbul ignore else */
+  if (targets.length > 0) {
+    setAttr(el, ATTR_ARIA_CONTROLS, targets.join(' '))
+    setStyle(el, STYLE_OVERFLOW_ANCHOR, 'none')
+  } else {
+    removeAttr(el, ATTR_ARIA_CONTROLS)
+    removeStyle(el, STYLE_OVERFLOW_ANCHOR)
+  }
+
+  // Add/Update our click listener(s)
+  // Wrap in a `requestAF()` to allow any previous
+  // click handling to occur first
+  requestAF(() => {
+    addClickListener(el, getInstanceFromDirective(vnode, binding))
+  })
+
+  // If targets array has changed, update
+  if (!looseEqual(targets, el[BV_TOGGLE_TARGETS])) {
+    // Update targets array to element storage
+    el[BV_TOGGLE_TARGETS] = targets
+    // Ensure `aria-controls` is up to date
+    // Request a state update from targets so that we can
+    // ensure expanded state is correct (in most cases)
+    targets.forEach(target => {
+      getEventRoot(getInstanceFromDirective(vnode, binding)).$emit(
+        ROOT_ACTION_EVENT_NAME_REQUEST_STATE,
+        target
+      )
+    })
+  }
+}
+
+/*
+ * Export our directive
+ */
+export const VBToggle = {
+  bind(el, binding, vnode) {
+    // State is initially collapsed until we receive a state event
+    el[BV_TOGGLE_STATE] = false
+    // Assume no targets initially
+    el[BV_TOGGLE_TARGETS] = []
+    // Add our root listeners
+    addRootListeners(el, getInstanceFromDirective(vnode, binding))
+    // Initial update of trigger
+    handleUpdate(el, binding, vnode)
+  },
+  componentUpdated: handleUpdate,
+  updated: handleUpdate,
+  unbind(el, binding, vnode) {
+    removeClickListener(el)
+    // Remove our $root listener
+    removeRootListeners(el, getInstanceFromDirective(vnode, binding))
+    // Reset custom props
+    resetProp(el, BV_TOGGLE_ROOT_HANDLER)
+    resetProp(el, BV_TOGGLE_CLICK_HANDLER)
+    resetProp(el, BV_TOGGLE_STATE)
+    resetProp(el, BV_TOGGLE_TARGETS)
+    // Reset classes/attrs/styles
+    removeClass(el, CLASS_BV_TOGGLE_COLLAPSED)
+    removeClass(el, CLASS_BV_TOGGLE_NOT_COLLAPSED)
+    removeAttr(el, ATTR_ARIA_EXPANDED)
+    removeAttr(el, ATTR_ARIA_CONTROLS)
+    removeAttr(el, ATTR_ROLE)
+    removeStyle(el, STYLE_OVERFLOW_ANCHOR)
+  }
+}