@gitlab/duo-ui 0.1.0

package/src/components/utilities/truncate_text/truncate_text.vue

@@ -0,0 +1,124 @@
+<script>
+import { GlResizeObserverDirective } from '../../../directives/resize_observer/resize_observer';
+import GlButton from '../../base/button/button.vue';
+import { STATES } from './constants';
+
+export default {
+  name: 'GlTruncateText',
+  components: {
+    GlButton,
+  },
+  directives: {
+    GlResizeObserver: GlResizeObserverDirective,
+  },
+  props: {
+    /**
+     * The text for the 'Show more' button
+     */
+    showMoreText: {
+      type: String,
+      required: false,
+      default: 'Show more',
+    },
+    /**
+     * The text for the 'Show less' button
+     */
+    showLessText: {
+      type: String,
+      required: false,
+      default: 'Show less',
+    },
+    /**
+     * The number of lines that are initially visible on larger screens
+     */
+    lines: {
+      type: Number,
+      required: false,
+      default: 3,
+    },
+    /**
+     * The number of lines that are initially visible on smaller screens
+     */
+    mobileLines: {
+      type: Number,
+      required: false,
+      default: 10,
+    },
+    /**
+     * Props that are passed to the toggle button
+     */
+    toggleButtonProps: {
+      type: Object,
+      required: false,
+      default() {
+        return {};
+      },
+    },
+  },
+  data() {
+    return {
+      state: STATES.INITIAL,
+    };
+  },
+  computed: {
+    showTruncationToggle() {
+      return this.isTruncated || this.isExtended;
+    },
+    truncationToggleText() {
+      return this.isTruncated ? this.showMoreText : this.showLessText;
+    },
+    cssVariables() {
+      return { '--lines': this.lines, '--mobile-lines': this.mobileLines };
+    },
+    truncationClasses() {
+      return this.isExtended ? null : 'gl-truncate-text gl-overflow-hidden';
+    },
+    ariaExpanded() {
+      return (!this.isTruncated).toString();
+    },
+    isTruncated() {
+      return this.state === STATES.TRUNCATED;
+    },
+    isExtended() {
+      return this.state === STATES.EXTENDED;
+    },
+  },
+  methods: {
+    onResize({ target }) {
+      if (target.scrollHeight > target.offsetHeight) {
+        this.state = STATES.TRUNCATED;
+      } else if (this.isTruncated) {
+        this.state = STATES.INITIAL;
+      }
+    },
+    toggleTruncation() {
+      if (this.isTruncated) {
+        this.state = STATES.EXTENDED;
+      } else if (this.isExtended) {
+        this.state = STATES.TRUNCATED;
+      }
+    },
+  },
+};
+</script>
+
+<template>
+  <section>
+    <article
+      v-gl-resize-observer="onResize"
+      :class="truncationClasses"
+      :style="cssVariables"
+      :aria-expanded="ariaExpanded"
+    >
+      <!-- @slot Text content -->
+      <slot></slot>
+    </article>
+    <gl-button
+      v-if="showTruncationToggle"
+      v-bind="toggleButtonProps"
+      variant="link"
+      @click="toggleTruncation"
+      >{{ truncationToggleText }}</gl-button
+    >
+  </section>
+</template>

package/src/config.js

@@ -0,0 +1,86 @@
+import Vue from 'vue';
+import translationKeys from '../translations';
+import { BVConfigPlugin } from './vendor/bootstrap-vue/src/bv-config';
+import { tooltipDelay } from './utils/constants';
+
+const tooltipGlobalConfig = {
+  // Work around for https://github.com/bootstrap-vue/bootstrap-vue/issues/6507
+  boundaryPadding: 5,
+  customClass: 'gl-tooltip',
+  delay: tooltipDelay,
+};
+
+const popoverDelayConfig = {
+  show: 50, // BootstrapVue's default delay on show.
+  hide: 150, // Increased hide delay so that it doesn't disappear to quickly when user attempts to interact with the content.
+};
+
+/**
+ * Guard against nonexistent localStorage,
+ * or corrupted localStorage
+ *
+ * localStorage access is not possible in certain environments like
+ * - in iframe usage in Chrome if embedded on another domain
+ * - tests / node
+ */
+try {
+  const glTooltipDelay = localStorage.getItem('gl-tooltip-delay');
+
+  if (glTooltipDelay) {
+    tooltipGlobalConfig.delay = JSON.parse(glTooltipDelay);
+  }
+} catch (e) {
+  // localStorage doesn't exist (or the value is not properly formatted)
+}
+
+export const i18n = translationKeys;
+
+let configured = false;
+
+/**
+ * Set GitLab UI configuration.
+ *
+ * @typedef {object} GitLabUIConfiguration
+ * @template TValue=string
+ * @property {undefined | Object} translations Generic translations for component labels to fall back to.
+ */
+const setConfigs = ({ translations } = {}) => {
+  if (configured) {
+    if (process.env.NODE_ENV === 'development') {
+      throw new Error('GitLab UI can only be configured once!');
+    }
+
+    return;
+  }
+  configured = true;
+
+  Vue.use(BVConfigPlugin, {
+    BTooltip: tooltipGlobalConfig,
+    BPopover: {
+      delay: popoverDelayConfig,
+    },
+  });
+
+  if (typeof translations === 'object') {
+    if (process.env.NODE_ENV === 'development') {
+      const undefinedTranslationKeys = Object.keys(i18n).reduce((acc, current) => {
+        if (!(current in translations)) {
+          acc.push(current);
+        }
+        return acc;
+      }, []);
+      if (undefinedTranslationKeys.length) {
+        /* eslint-disable no-console */
+        console.warn(
+          '[@gitlab/ui] The following translations have not been given, so will fall back to their default US English strings:'
+        );
+        console.table(undefinedTranslationKeys);
+        /* eslint-enable no-console */
+      }
+    }
+
+    Object.assign(i18n, translations);
+  }
+};
+
+export default setConfigs;

package/src/directives/collapse_toggle.js

@@ -0,0 +1 @@
+export { VBToggle as GlCollapseToggleDirective } from '../vendor/bootstrap-vue/src/directives/toggle/toggle';

package/src/directives/hover_load/hover_load.js

@@ -0,0 +1,46 @@
+import isFunction from 'lodash/isFunction';
+
+export const DELAY_ON_HOVER = 100;
+let mouseOverTimer;
+let mouseOverHandler;
+
+const bind = (el, { value: loadHandler }) => {
+  if (!isFunction(loadHandler)) {
+    throw TypeError('Directive value must be a function');
+  }
+
+  const mouseOutHandler = () => {
+    if (mouseOverTimer) {
+      clearTimeout(mouseOverTimer);
+      mouseOverTimer = undefined;
+    }
+  };
+
+  mouseOverHandler = () => {
+    el.addEventListener('mouseout', mouseOutHandler, { passive: true });
+
+    mouseOverTimer = setTimeout(() => {
+      loadHandler(el);
+
+      // Only execute once
+      el.removeEventListener('mouseover', mouseOverHandler, true);
+      el.removeEventListener('mouseout', mouseOutHandler);
+
+      mouseOverTimer = undefined;
+    }, DELAY_ON_HOVER);
+  };
+
+  el.addEventListener('mouseover', mouseOverHandler, {
+    capture: true,
+    passive: true,
+  });
+};
+
+const unbind = (el) => {
+  el.removeEventListener('mouseover', mouseOverHandler, true);
+};
+
+export const HoverLoadDirective = {
+  bind,
+  unbind,
+};

package/src/directives/hover_load/hover_load.md

@@ -0,0 +1,22 @@
+A Vue Directive to help with preloading resources when hovering over an element.
+
+## Usage
+
+```html
+<script>
+import { GlHoverLoadDirective } from '@gitlab/ui';
+
+export default {
+  directives: { GlHoverLoadDirective },
+  methods: {
+    handlePreload() {
+      fetch('some/endpoint');
+    },
+  },
+};
+</script>
+
+<template>
+  <div v-gl-hover-load="handlePreload">Hover me to preload</div>
+</template>
+```

package/src/directives/modal.js

@@ -0,0 +1 @@
+export { VBModal as GlModalDirective } from '../vendor/bootstrap-vue/src/directives/modal/modal';

package/src/directives/outside/outside.js

@@ -0,0 +1,151 @@
+/**
+ * Map<HTMLElement, { callback: Function, eventTypes: Array<string> }>
+ */
+const callbacks = new Map();
+const click = 'click';
+const focusin = 'focusin';
+const supportedEventTypes = [click, focusin];
+const defaultEventType = click;
+
+/**
+ * A Set to keep track of currently active event types.
+ * This ensures that event listeners are only added for the event types that are in use.
+ *
+ * @type {Set<string>}
+ */
+const activeEventTypes = new Set();
+let lastMousedown = null;
+
+const globalListener = (event) => {
+  callbacks.forEach(({ callback, eventTypes }, element) => {
+    const originalEvent = event.type === click ? lastMousedown || event : event;
+    if (
+      // Ignore events that aren't targeted outside the element
+      element.contains(originalEvent.target) ||
+      // Ignore events that aren't the specified types for this element
+      !eventTypes.includes(event.type)
+    ) {
+      return;
+    }
+
+    try {
+      callback(event);
+    } catch (e) {
+      if (process.env.NODE_ENV !== 'production') {
+        // eslint-disable-next-line no-console
+        console.error(e);
+      }
+    }
+  });
+  if (event.type === click) {
+    lastMousedown = null;
+  }
+};
+
+// We need to listen for mouse events because text selection fires click event only when selection ends.
+// This means that the click event target could differ from the element where it originally started.
+// As example: if we use mouse events we could guarantee that selecting text within a dropdown won't close it.
+const onMousedown = (event) => {
+  lastMousedown = event;
+};
+
+const startListening = (eventTypes) => {
+  eventTypes.forEach((eventType) => {
+    if (!activeEventTypes.has(eventType)) {
+      // Listening to mousedown events, ensures that a text selection doesn't trigger the
+      // GlOutsideDirective 'click' callback if the selection started within the target element.
+      if (eventType === click) {
+        document.addEventListener('mousedown', onMousedown);
+      }
+
+      // Added { capture: true } to all event types to prevent the behavior discussed in https://gitlab.com/gitlab-org/gitlab-ui/-/merge_requests/1686#note_412545027
+      // Ensures the event listener handles the event in the capturing phase, avoiding issues encountered previously.
+      // Cannot be tested with Jest or Cypress, but can be tested with Playwright in the future: https://gitlab.com/gitlab-org/gitlab-ui/-/merge_requests/4272#note_1947425384
+      document.addEventListener(eventType, globalListener, { capture: true });
+      activeEventTypes.add(eventType);
+    }
+  });
+
+  lastMousedown = null;
+};
+
+const stopListening = (eventTypesToUnbind) => {
+  eventTypesToUnbind.forEach((eventType) => {
+    if (activeEventTypes.has(eventType)) {
+      if ([...callbacks.values()].every(({ eventTypes }) => !eventTypes.includes(eventType))) {
+        document.removeEventListener(eventType, globalListener);
+        activeEventTypes.delete(eventType);
+      }
+    }
+  });
+
+  if (eventTypesToUnbind.includes(click) && !activeEventTypes.has(click)) {
+    document.removeEventListener('mousedown', onMousedown);
+  }
+};
+
+function parseBinding({ arg, value, modifiers }) {
+  const modifiersList = Object.keys(modifiers);
+
+  if (process.env.NODE_ENV !== 'production') {
+    if (typeof value !== 'function') {
+      throw new Error(`[GlOutsideDirective] Value must be a function; got ${typeof value}!`);
+    }
+
+    if (typeof arg !== 'undefined') {
+      throw new Error(
+        `[GlOutsideDirective] Arguments are not supported. Consider using modifiers instead.`
+      );
+    }
+
+    const unsupportedModifiers = modifiersList.filter(
+      (modifier) => !supportedEventTypes.includes(modifier)
+    );
+
+    if (unsupportedModifiers.length > 0) {
+      throw new Error(
+        `[GlOutsideDirective] Cannot bind ${unsupportedModifiers.join(', ')} events; supported event types are: ${supportedEventTypes.join(
+          ', '
+        )}`
+      );
+    }
+  }
+
+  return {
+    callback: value,
+    eventTypes: modifiersList.length > 0 ? modifiersList : [defaultEventType],
+  };
+}
+
+const bind = (el, bindings) => {
+  const { callback, eventTypes } = parseBinding(bindings);
+
+  if (callbacks.has(el)) {
+    // This element is already bound. This is possible if two components, which
+    // share the same root node, (i.e., one is a higher-order component
+    // wrapping another) _both_ have this directive applied.
+    //
+    // Because Vue binds directives in the direction towards the root, only the
+    // deepest instance of this directive will be bound.
+    //
+    // A future iteration may add support for binding all instances on a given
+    // element.
+    return;
+  }
+
+  callbacks.set(el, { callback, eventTypes });
+  startListening(eventTypes);
+};
+
+const unbind = (el) => {
+  const entry = callbacks.get(el);
+  if (entry) {
+    callbacks.delete(el);
+    stopListening(entry.eventTypes);
+  }
+};
+
+export const OutsideDirective = {
+  bind,
+  unbind,
+};

package/src/directives/outside/outside.md

@@ -0,0 +1,140 @@
+A Vue Directive to call a callback when a supported event type occurs *outside* of the element
+the directive is bound to. Any events on the element or any descendant elements are ignored.
+The directive supports the event types `click` and `focusin` and can be configured in several ways.
+If no event type is set, `click` is the default.
+
+## Usage
+
+### Default
+
+The following example listens for click events outside the specified element:
+
+```html
+<script>
+import { GlOutsideDirective as Outside } from '@gitlab/ui';
+
+export default {
+  directives: { Outside },
+  methods: {
+    onClick(event) {
+      console.log('User clicked somewhere outside of this component', event);
+    },
+  },
+};
+</script>
+
+<template>
+  <div v-outside="onClick">Click anywhere but here</div>
+</template>
+```
+
+### When binding another event type than `click`
+
+You can specify event types as modifiers. The following example listens for `focusin` events,
+but not for `click`. With this implementation:
+
+```html
+<script>
+export default {
+  methods: {
+    onFocusin(event) {
+      console.log('User set the focus somewhere outside of this component', event);
+    }
+  }
+};
+</script>
+
+<template>
+  <div v-outside.focusin="onFocusin">...</div>
+</template>
+```
+
+### When binding multiple event types
+
+You can specify multiple event types by providing multiple modifiers. The following example
+listens for `click` and `focusin` events:
+
+```html
+<script>
+export default {
+  methods: {
+    onEvent(event) {
+      console.log('Event occurred outside the element:', event);
+    }
+  }
+};
+</script>
+
+<template>
+  <div v-outside.click.focusin="onEvent">...</div>
+</template>
+```
+
+💡 The callback function receives the `event` as a parameter. You can use the `event.type`
+property to execute different code paths depending on which event triggered the callback.
+
+### When handler expects arguments
+
+In case a click handler expects an arument to be passed, simple `v-outside="onClick('foo')"` will
+invoke the handler instantly when mounting the component and the directive won't be active. The
+simplest solution to pass the arguments to the directive is to wrap the handler into an anonumous
+function.
+
+```html
+<script>
+import { GlOutsideDirective as Outside } from '@gitlab/ui';
+
+export default {
+  directives: { Outside },
+  methods: {
+    onClick(event, foo) {
+      console.log('Event occurred outside the element:', event);
+      console.log('An argument was passed along:', foo);
+    },
+  },
+};
+</script>
+
+<template>
+  <div v-outside="(event) => onClick(event, 'foo')">Click anywhere but here</div>
+</template>
+```
+
+## Caveats
+
+* Clicks cannot be detected across document boundaries (e.g., across an
+  `iframe` boundary), in either direction.
+* Clicks on focusable elements, such as buttons or input fields, will fire both
+  `click` and `focusin` events. When both event types are registered,
+  the callback will be executed twice. To prevent executing the same code twice
+  after only one user interaction, use a flag in the callback to stop its
+  execution. Example:
+
+  ```html
+    <script>
+    export default {
+      data: () => ({
+        isOpen: false,
+      }),
+      methods: {
+        openDropdown() {
+          this.isOpen = true;
+        },
+        closeDropdown() {
+          if(!this.isOpen) {
+            return
+          }
+
+          // more code
+
+          this.isOpen = false;
+        }
+      }
+    };
+    </script>
+
+    <template>
+      <button type="button" @click="openDropdown">Open</button>
+      <div v-outside.click.focusin="closeDropdown">...</div>
+    </template>
+  ```

package/src/directives/resize_observer/resize_observer.js

@@ -0,0 +1,45 @@
+import isFunction from 'lodash/isFunction';
+
+let observer = null;
+
+const attachObserver = (el, resizeHandler) => {
+  if (!isFunction(resizeHandler)) {
+    throw TypeError('directive value must be a function');
+  }
+
+  if (!observer) {
+    // the observer instance is shared for performance reasons
+    // more information: https://github.com/WICG/ResizeObserver/issues/59
+    observer = new ResizeObserver((entries) => {
+      entries.forEach((event) => {
+        event.target.glResizeHandler(event);
+      });
+    });
+  }
+
+  el.glResizeHandler = resizeHandler;
+  observer.observe(el);
+};
+
+const detachObserver = (el) => {
+  if (el.glResizeHandler) {
+    delete el.glResizeHandler;
+    observer?.unobserve(el);
+  }
+};
+
+export const GlResizeObserverDirective = {
+  bind(el, { value: resizeHandler, arg: enabled = true }) {
+    if (enabled) {
+      attachObserver(el, resizeHandler);
+    }
+  },
+  update(el, { value: resizeHandler, arg: enabled = true }) {
+    if (enabled) {
+      attachObserver(el, resizeHandler);
+    } else {
+      detachObserver(el);
+    }
+  },
+  unbind: detachObserver,
+};

package/src/directives/resize_observer/resize_observer.md

@@ -0,0 +1,54 @@
+This directive can be used to get notified whenever a given element's size (width or height) changes
+and to retrieve the updated dimensions.
+
+Under the hood, it leverages the [Resize Observer API](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserver).
+If you use GitLab UI in an older browser which doesn't support the Resize Observer API,
+you can use a [polyfill](https://github.com/que-etc/resize-observer-polyfill).
+
+The directive accepts a callback as a value and passes on the received
+[contentRect](https://developer.mozilla.org/en-US/docs/Web/API/ResizeObserverEntry/contentRect)
+and the target element whenever a resize event gets triggered.
+
+```html
+<script>
+export default {
+  data() {
+    return {
+      width: 0,
+      height: 0,
+    };
+  },
+  methods: {
+    handleResize({ contentRect: { width, height } }) {
+      this.width = width;
+      this.height = height;
+    },
+  },
+};
+</script>
+<template>
+  <div v-gl-resize-observer-directive="handleResize">
+    <p>{{ width }} x {{ height }}</p>
+  </div>
+</template>
+```
+
+The observer can be toggled on or off by passing a boolean argument to the directive:
+
+```html
+<script>
+export default {
+  data() {
+    return {
+      shouldObserve: true,
+    };
+  },
+  methods: {
+    handleResize() {},
+  },
+};
+</script>
+<template>
+  <div v-gl-resize-observer-directive[shouldObserve]="handleResize"></div>
+</template>
+```

package/src/directives/safe_html/constants.js

@@ -0,0 +1,14 @@
+// See https://gitlab.com/gitlab-org/gitlab-ui/-/issues/1421#note_617098438
+// for more details
+export const forbiddenDataAttrs = [
+  'data-remote',
+  'data-url',
+  'data-type',
+  'data-method',
+  'data-disable-with',
+  'data-disabled',
+  'data-disable',
+  'data-turbo',
+];
+
+export const forbiddenTags = ['style', 'mstyle', 'form'];