@gitlab/ui 86.5.1 → 86.6.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [86.6.0](https://gitlab.com/gitlab-org/gitlab-ui/compare/v86.5.1...v86.6.0) (2024-07-10)
+
+
+### Features
+
+* **OutsideDirective:** Add Event Listener for focusin ([aee99c5](https://gitlab.com/gitlab-org/gitlab-ui/commit/aee99c56b926d9468030774c4bd33eac01f4f601))
+
 ## [86.5.1](https://gitlab.com/gitlab-org/gitlab-ui/compare/v86.5.0...v86.5.1) (2024-07-10)
 
 

package/dist/directives/outside/outside.js

@@ -1,19 +1,32 @@
 /**
- * Map<HTMLElement, Function>
+ * Map<HTMLElement, { callback: Function, eventTypes: Array<string> }>
  */
 const callbacks = new Map();
+const click = 'click';
+const focusin = 'focusin';
+const supportedEventTypes = [click, focusin];
+const defaultEventType = click;
 
 /**
- * Is a global listener already set up?
+ * 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>}
  */
-let listening = false;
+const activeEventTypes = new Set();
 let lastMousedown = null;
 const globalListener = event => {
-  callbacks.forEach((callback, element) => {
-    const originalEvent = lastMousedown || event;
+  callbacks.forEach((_ref, element) => {
+    let {
+      callback,
+      eventTypes
+    } = _ref;
+    const originalEvent = event.type === click ? lastMousedown || event : event;
     if (
     // Ignore events that aren't targeted outside the element
-    element.contains(originalEvent.target)) {
+    element.contains(originalEvent.target) ||
+    // Ignore events that aren't the specified types for this element
+    !eventTypes.includes(event.type)) {
       return;
     }
     try {
@@ -25,7 +38,9 @@ const globalListener = event => {
       }
     }
   });
-  lastMousedown = null;
+  if (event.type === click) {
+    lastMousedown = null;
+  }
 };
 
 // We need to listen for mouse events because text selection fires click event only when selection ends.
@@ -34,39 +49,72 @@ const globalListener = event => {
 const onMousedown = event => {
   lastMousedown = event;
 };
-const startListening = () => {
-  if (listening) {
-    return;
-  }
-  document.addEventListener('mousedown', onMousedown);
-  // Added { capture: true } 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('click', globalListener, {
-    capture: true
+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);
+    }
   });
-  listening = true;
   lastMousedown = null;
 };
-const stopListening = () => {
-  if (!listening) {
-    return;
+const stopListening = eventTypesToUnbind => {
+  eventTypesToUnbind.forEach(eventType => {
+    if (activeEventTypes.has(eventType)) {
+      if ([...callbacks.values()].every(_ref2 => {
+        let {
+          eventTypes
+        } = _ref2;
+        return !eventTypes.includes(eventType);
+      })) {
+        document.removeEventListener(eventType, globalListener);
+        activeEventTypes.delete(eventType);
+      }
+    }
+  });
+  if (eventTypesToUnbind.includes(click) && !activeEventTypes.has(click)) {
+    document.removeEventListener('mousedown', onMousedown);
   }
-  document.removeEventListener('mousedown', onMousedown);
-  document.removeEventListener('click', globalListener);
-  listening = false;
 };
-const bind = (el, _ref) => {
+function parseBinding(_ref3) {
   let {
+    arg,
     value,
-    arg = 'click'
-  } = _ref;
-  if (typeof value !== 'function') {
-    throw new Error(`[GlOutsideDirective] Value must be a function; got ${typeof value}!`);
-  }
-  if (arg !== 'click') {
-    throw new Error(`[GlOutsideDirective] Cannot bind ${arg} events; only click events are currently supported!`);
+    modifiers
+  } = _ref3;
+  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.`);
+    }
+    if (modifiersList.some(modifier => !supportedEventTypes.includes(modifier))) {
+      throw new Error(`[GlOutsideDirective] Cannot bind ${modifiersList} 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
@@ -79,15 +127,17 @@ const bind = (el, _ref) => {
     // element.
     return;
   }
-  if (!listening) {
-    startListening();
-  }
-  callbacks.set(el, value);
+  callbacks.set(el, {
+    callback,
+    eventTypes
+  });
+  startListening(eventTypes);
 };
 const unbind = el => {
-  callbacks.delete(el);
-  if (callbacks.size === 0) {
-    stopListening();
+  const entry = callbacks.get(el);
+  if (entry) {
+    callbacks.delete(el);
+    stopListening(entry.eventTypes);
   }
 };
 const OutsideDirective = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitlab/ui",
-  "version": "86.5.1",
+  "version": "86.6.0",
   "description": "GitLab UI Components",
   "license": "MIT",
   "main": "dist/index.js",

package/src/directives/outside/outside.js

@@ -1,20 +1,29 @@
 /**
- * Map<HTMLElement, Function>
+ * Map<HTMLElement, { callback: Function, eventTypes: Array<string> }>
  */
 const callbacks = new Map();
+const click = 'click';
+const focusin = 'focusin';
+const supportedEventTypes = [click, focusin];
+const defaultEventType = click;
 
 /**
- * Is a global listener already set up?
+ * 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>}
  */
-let listening = false;
+const activeEventTypes = new Set();
 let lastMousedown = null;
 
 const globalListener = (event) => {
-  callbacks.forEach((callback, element) => {
-    const originalEvent = lastMousedown || 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)
+      element.contains(originalEvent.target) ||
+      // Ignore events that aren't the specified types for this element
+      !eventTypes.includes(event.type)
     ) {
       return;
     }
@@ -28,7 +37,9 @@ const globalListener = (event) => {
       }
     }
   });
-  lastMousedown = null;
+  if (event.type === click) {
+    lastMousedown = null;
+  }
 };
 
 // We need to listen for mouse events because text selection fires click event only when selection ends.
@@ -38,41 +49,73 @@ const onMousedown = (event) => {
   lastMousedown = event;
 };
 
-const startListening = () => {
-  if (listening) {
-    return;
-  }
+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);
+    }
+  });
 
-  document.addEventListener('mousedown', onMousedown);
-  // Added { capture: true } 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('click', globalListener, { capture: true });
-  listening = true;
   lastMousedown = null;
 };
 
-const stopListening = () => {
-  if (!listening) {
-    return;
-  }
+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);
+      }
+    }
+  });
 
-  document.removeEventListener('mousedown', onMousedown);
-  document.removeEventListener('click', globalListener);
-  listening = false;
+  if (eventTypesToUnbind.includes(click) && !activeEventTypes.has(click)) {
+    document.removeEventListener('mousedown', onMousedown);
+  }
 };
 
-const bind = (el, { value, arg = 'click' }) => {
-  if (typeof value !== 'function') {
-    throw new Error(`[GlOutsideDirective] Value must be a function; got ${typeof value}!`);
-  }
+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.`
+      );
+    }
 
-  if (arg !== 'click') {
-    throw new Error(
-      `[GlOutsideDirective] Cannot bind ${arg} events; only click events are currently supported!`
-    );
+    if (modifiersList.some((modifier) => !supportedEventTypes.includes(modifier))) {
+      throw new Error(
+        `[GlOutsideDirective] Cannot bind ${modifiersList} 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
@@ -86,18 +129,15 @@ const bind = (el, { value, arg = 'click' }) => {
     return;
   }
 
-  if (!listening) {
-    startListening();
-  }
-
-  callbacks.set(el, value);
+  callbacks.set(el, { callback, eventTypes });
+  startListening(eventTypes);
 };
 
 const unbind = (el) => {
-  callbacks.delete(el);
-
-  if (callbacks.size === 0) {
-    stopListening();
+  const entry = callbacks.get(el);
+  if (entry) {
+    callbacks.delete(el);
+    stopListening(entry.eventTypes);
   }
 };
 

package/src/directives/outside/outside.md

@@ -1,8 +1,14 @@
-A Vue Directive to call a callback when a click occurs *outside* of the element
-the directive is bound to. Any clicks on the element or any descendant elements are ignored.
+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';
@@ -22,6 +28,51 @@ export default {
 </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
@@ -36,19 +87,54 @@ import { GlOutsideDirective as Outside } from '@gitlab/ui';
 export default {
   directives: { Outside },
   methods: {
-    onClick(foo) {
-      // This
+    onClick(event, foo) {
+      console.log('Event occurred outside the element:', event);
+      console.log('An argument was passed along:', foo);
     },
   },
 };
 </script>
 
 <template>
-  <div v-outside="() => onClick('foo')">Click anywhere but here</div>
+  <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
+* 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>
+  ```