@gitlab/duo-ui 0.1.0

package/src/components/base/new_dropdowns/base_dropdown/base_dropdown.vue

@@ -0,0 +1,507 @@
+<script>
+import uniqueId from 'lodash/uniqueId';
+import { computePosition, autoUpdate, offset, size, autoPlacement, shift } from '@floating-ui/dom';
+import {
+  buttonCategoryOptions,
+  buttonSizeOptions,
+  dropdownPlacements,
+  dropdownAllowedAutoPlacements,
+  dropdownVariantOptions,
+} from '../../../../utils/constants';
+import {
+  GL_DROPDOWN_SHOWN,
+  GL_DROPDOWN_HIDDEN,
+  GL_DROPDOWN_BEFORE_CLOSE,
+  GL_DROPDOWN_FOCUS_CONTENT,
+  ENTER,
+  SPACE,
+  ARROW_DOWN,
+  GL_DROPDOWN_CONTENTS_CLASS,
+  POSITION_ABSOLUTE,
+  POSITION_FIXED,
+} from '../constants';
+import { logWarning, isElementTabbable, isElementFocusable } from '../../../../utils/utils';
+import { OutsideDirective } from '../../../../directives/outside/outside';
+import GlButton from '../../button/button.vue';
+import GlIcon from '../../icon/icon.vue';
+import { DEFAULT_OFFSET, FIXED_WIDTH_CLASS } from './constants';
+
+export const BASE_DROPDOWN_CLASS = 'gl-new-dropdown';
+
+export default {
+  name: 'BaseDropdown',
+  BASE_DROPDOWN_CLASS,
+  components: {
+    GlButton,
+    GlIcon,
+  },
+  directives: { Outside: OutsideDirective },
+  props: {
+    toggleText: {
+      type: String,
+      required: false,
+      default: '',
+    },
+    textSrOnly: {
+      type: Boolean,
+      required: false,
+      default: false,
+    },
+    block: {
+      type: Boolean,
+      required: false,
+      default: false,
+    },
+    category: {
+      type: String,
+      required: false,
+      default: buttonCategoryOptions.primary,
+      validator: (value) => Object.keys(buttonCategoryOptions).includes(value),
+    },
+    variant: {
+      type: String,
+      required: false,
+      default: dropdownVariantOptions.default,
+      validator: (value) => Object.keys(dropdownVariantOptions).includes(value),
+    },
+    size: {
+      type: String,
+      required: false,
+      default: 'medium',
+      validator: (value) => Object.keys(buttonSizeOptions).includes(value),
+    },
+    icon: {
+      type: String,
+      required: false,
+      default: '',
+    },
+    disabled: {
+      type: Boolean,
+      required: false,
+      default: false,
+    },
+    loading: {
+      type: Boolean,
+      required: false,
+      default: false,
+    },
+    toggleClass: {
+      type: [String, Array, Object],
+      required: false,
+      default: null,
+    },
+    noCaret: {
+      type: Boolean,
+      required: false,
+      default: false,
+    },
+    placement: {
+      type: String,
+      required: false,
+      default: 'bottom-start',
+      validator: (value) => {
+        if (['left', 'center', 'right'].includes(value)) {
+          logWarning(
+            `GlDisclosureDropdown/GlCollapsibleListbox: "${value}" placement is deprecated.
+            Use ${dropdownPlacements[value]} instead.`
+          );
+        }
+
+        return Object.keys(dropdownPlacements).includes(value);
+      },
+    },
+    // ARIA props
+    ariaHaspopup: {
+      type: [String, Boolean],
+      required: false,
+      default: false,
+      validator: (value) => {
+        return ['menu', 'listbox', 'tree', 'grid', 'dialog', true, false].includes(value);
+      },
+    },
+    /**
+     * Id that will be referenced by `aria-labelledby` attribute of the dropdown content`
+     */
+    toggleId: {
+      type: String,
+      required: true,
+    },
+    /**
+     * The `aria-labelledby` attribute value for the  toggle `button`
+     */
+    ariaLabelledby: {
+      type: String,
+      required: false,
+      default: null,
+    },
+    /**
+     * Custom value to be passed to the offset middleware.
+     * https://floating-ui.com/docs/offset
+     */
+    offset: {
+      type: [Number, Object],
+      required: false,
+      default: () => ({ mainAxis: DEFAULT_OFFSET }),
+    },
+    fluidWidth: {
+      type: Boolean,
+      required: false,
+      default: false,
+    },
+    /**
+     * Strategy to be applied by computePosition. If this is set to fixed, the dropdown's position
+     * needs to be set to fixed in CSS as well.
+     * https://floating-ui.com/docs/computePosition#strategy
+     */
+    positioningStrategy: {
+      type: String,
+      required: false,
+      default: POSITION_ABSOLUTE,
+      validator: (strategy) => [POSITION_ABSOLUTE, POSITION_FIXED].includes(strategy),
+    },
+  },
+  data() {
+    return {
+      openedYet: false,
+      visible: false,
+      baseDropdownId: uniqueId('base-dropdown-'),
+    };
+  },
+  computed: {
+    hasNoVisibleToggleText() {
+      return !this.toggleText?.length || this.textSrOnly;
+    },
+    isIconOnly() {
+      return Boolean(this.icon && this.hasNoVisibleToggleText);
+    },
+    isEllipsisButton() {
+      return this.isIconOnly && this.icon === 'ellipsis_h';
+    },
+    isCaretOnly() {
+      return !this.noCaret && !this.icon && this.hasNoVisibleToggleText;
+    },
+    ariaAttributes() {
+      return {
+        'aria-haspopup': this.ariaHaspopup,
+        'aria-expanded': String(this.visible),
+        'aria-controls': this.baseDropdownId,
+        'aria-labelledby': this.toggleLabelledBy,
+      };
+    },
+    toggleButtonClasses() {
+      return [
+        this.toggleClass,
+        {
+          'gl-new-dropdown-toggle': true,
+          'button-ellipsis-horizontal': this.isEllipsisButton,
+          'gl-new-dropdown-icon-only btn-icon': this.isIconOnly && !this.isEllipsisButton,
+          'gl-new-dropdown-toggle-no-caret': this.noCaret,
+          'gl-new-dropdown-caret-only btn-icon': this.isCaretOnly,
+        },
+      ];
+    },
+    toggleButtonTextClasses() {
+      return this.block ? 'gl-w-full' : '';
+    },
+    toggleLabelledBy() {
+      return this.ariaLabelledby ? `${this.ariaLabelledby} ${this.toggleId}` : this.toggleId;
+    },
+    isDefaultToggle() {
+      return !this.$scopedSlots.toggle;
+    },
+    toggleOptions() {
+      if (this.isDefaultToggle) {
+        return {
+          is: GlButton,
+          icon: this.icon,
+          block: this.block,
+          buttonTextClasses: this.toggleButtonTextClasses,
+          category: this.category,
+          variant: this.variant,
+          size: this.size,
+          disabled: this.disabled,
+          loading: this.loading,
+          class: this.toggleButtonClasses,
+          ...this.ariaAttributes,
+          listeners: {
+            keydown: (event) => this.onKeydown(event),
+            click: (event) => this.toggle(event),
+          },
+        };
+      }
+
+      return {
+        is: 'div',
+        class: 'gl-new-dropdown-custom-toggle',
+        listeners: {
+          keydown: (event) => this.onKeydown(event),
+          click: (event) => this.toggle(event),
+        },
+      };
+    },
+    toggleListeners() {
+      return this.toggleOptions.listeners;
+    },
+
+    toggleAttributes() {
+      const { listeners, is, ...attributes } = this.toggleOptions;
+
+      return attributes;
+    },
+    toggleComponent() {
+      return this.toggleOptions.is;
+    },
+    toggleElement() {
+      return this.$refs.toggle.$el || this.$refs.toggle?.firstElementChild;
+    },
+    panelClasses() {
+      return {
+        '!gl-block': this.visible,
+        [FIXED_WIDTH_CLASS]: !this.fluidWidth,
+        'gl-fixed': this.openedYet && this.isFixed,
+        'gl-absolute': this.openedYet && !this.isFixed,
+      };
+    },
+    isFixed() {
+      return this.positioningStrategy === POSITION_FIXED;
+    },
+    floatingUIConfig() {
+      const placement = dropdownPlacements[this.placement];
+      const [, alignment] = placement.split('-');
+      return {
+        placement,
+        strategy: this.positioningStrategy,
+        middleware: [
+          offset(this.offset),
+          autoPlacement({
+            alignment,
+            allowedPlacements: dropdownAllowedAutoPlacements[this.placement],
+          }),
+          shift(),
+          size({
+            apply: ({ availableHeight, elements }) => {
+              const contentsEl = elements.floating.querySelector(`.${GL_DROPDOWN_CONTENTS_CLASS}`);
+              if (!contentsEl) {
+                return;
+              }
+
+              const contentsAvailableHeight =
+                availableHeight - (this.nonScrollableContentHeight ?? 0) - DEFAULT_OFFSET;
+              Object.assign(contentsEl.style, {
+                maxHeight: `${Math.max(contentsAvailableHeight, 0)}px`,
+              });
+            },
+          }),
+        ],
+      };
+    },
+  },
+  watch: {
+    ariaAttributes: {
+      deep: true,
+      handler(ariaAttributes) {
+        if (this.$scopedSlots.toggle) {
+          Object.keys(ariaAttributes).forEach((key) => {
+            this.toggleElement.setAttribute(key, ariaAttributes[key]);
+          });
+        }
+      },
+    },
+  },
+  mounted() {
+    this.checkToggleFocusable();
+  },
+  beforeDestroy() {
+    this.stopFloating();
+  },
+  methods: {
+    checkToggleFocusable() {
+      if (!isElementFocusable(this.toggleElement) && !isElementTabbable(this.toggleElement)) {
+        logWarning(
+          `GlDisclosureDropdown/GlCollapsibleListbox: Toggle is missing a 'tabindex' and cannot be focused.
+          Use 'a' or 'button' element instead or make sure to add 'role="button"' along with 'tabindex' otherwise.`,
+          this.$el
+        );
+      }
+    },
+    async startFloating() {
+      this.calculateNonScrollableAreaHeight();
+      this.observer = new MutationObserver(this.calculateNonScrollableAreaHeight);
+      this.observer.observe(this.$refs.content, {
+        attributes: false,
+        childList: true,
+        subtree: true,
+      });
+
+      this.stopAutoUpdate = autoUpdate(this.toggleElement, this.$refs.content, async () => {
+        const { x, y } = await computePosition(
+          this.toggleElement,
+          this.$refs.content,
+          this.floatingUIConfig
+        );
+
+        /**
+         * Due to the asynchronous nature of computePosition, it's technically possible for the
+         * component to have been destroyed by the time the promise resolves. In such case, we exit
+         * early to prevent a TypeError.
+         */
+        if (!this.$refs.content) return;
+
+        Object.assign(this.$refs.content.style, {
+          left: `${x}px`,
+          top: `${y}px`,
+        });
+      });
+    },
+    stopFloating() {
+      this.observer?.disconnect();
+      this.stopAutoUpdate?.();
+    },
+    async toggle(event) {
+      if (event && this.visible) {
+        let prevented = false;
+        this.$emit(GL_DROPDOWN_BEFORE_CLOSE, {
+          originalEvent: event,
+          preventDefault() {
+            prevented = true;
+          },
+        });
+        if (prevented) return false;
+      }
+      this.visible = !this.visible;
+
+      if (this.visible) {
+        // The dropdown needs to be actually visible before we compute its position with Floating UI.
+        await this.$nextTick();
+        this.openedYet = true;
+        /**
+         * We wait until the dropdown's position has been computed before emitting the `shown` event.
+         * This ensures that, if the parent component attempts to focus an inner element, the dropdown
+         * is already properly placed in the page. Otherwise, the page would scroll back to the top.
+         */
+        this.startFloating();
+
+        this.$emit(GL_DROPDOWN_SHOWN);
+      } else {
+        this.stopFloating();
+        this.$emit(GL_DROPDOWN_HIDDEN);
+      }
+
+      // this is to check whether `toggle` was prevented or not
+      return true;
+    },
+    open() {
+      if (this.visible) {
+        return;
+      }
+      this.toggle();
+    },
+    close(event) {
+      if (!this.visible) {
+        return;
+      }
+      this.toggle(event);
+    },
+    /**
+     * Closes the dropdown and returns the focus to the toggle unless it has has moved outside
+     * of the dropdown, meaning that the consumer needed to put some other element in focus.
+     *
+     * @param {KeyboardEvent?} event The keyboard event that caused the dropdown to close.
+     */
+    async closeAndFocus(event) {
+      if (!this.visible) {
+        return;
+      }
+
+      const hadFocusWithin = this.$el.contains(document.activeElement);
+      const hasToggled = await this.toggle(event);
+
+      if (!hadFocusWithin) {
+        return;
+      }
+
+      if (hasToggled) {
+        this.focusToggle();
+      }
+    },
+    focusToggle() {
+      this.toggleElement.focus();
+    },
+    onKeydown(event) {
+      const {
+        code,
+        target: { tagName },
+      } = event;
+
+      let toggleOnEnter = true;
+      let toggleOnSpace = true;
+
+      if (tagName === 'BUTTON') {
+        toggleOnEnter = false;
+        toggleOnSpace = false;
+      } else if (tagName === 'A') {
+        toggleOnEnter = false;
+      }
+
+      if ((code === ENTER && toggleOnEnter) || (code === SPACE && toggleOnSpace)) {
+        this.toggle(event);
+      }
+
+      if (code === ARROW_DOWN) {
+        this.$emit(GL_DROPDOWN_FOCUS_CONTENT, event);
+      }
+    },
+    calculateNonScrollableAreaHeight() {
+      const scrollableArea = this.$refs.content?.querySelector(`.${GL_DROPDOWN_CONTENTS_CLASS}`);
+      if (!scrollableArea) return;
+
+      const floatingElementBoundingBox = this.$refs.content.getBoundingClientRect();
+      const scrollableAreaBoundingBox = scrollableArea.getBoundingClientRect();
+      this.nonScrollableContentHeight =
+        floatingElementBoundingBox.height - scrollableAreaBoundingBox.height;
+    },
+  },
+};
+</script>
+
+<template>
+  <div
+    v-outside.click.focusin="close"
+    :class="[$options.BASE_DROPDOWN_CLASS, { '!gl-block': block }]"
+  >
+    <component
+      :is="toggleComponent"
+      v-bind="toggleAttributes"
+      :id="toggleId"
+      ref="toggle"
+      data-testid="base-dropdown-toggle"
+      v-on="toggleListeners"
+      @keydown.esc.stop.prevent="close"
+    >
+      <!-- @slot Custom toggle button content -->
+      <slot name="toggle">
+        <span class="gl-new-dropdown-button-text" :class="{ 'gl-sr-only': textSrOnly }">
+          {{ toggleText }}
+        </span>
+        <gl-icon
+          v-if="!noCaret"
+          class="gl-button-icon gl-new-dropdown-chevron"
+          name="chevron-down"
+        />
+      </slot>
+    </component>
+
+    <div
+      :id="baseDropdownId"
+      ref="content"
+      data-testid="base-dropdown-menu"
+      class="gl-new-dropdown-panel"
+      :class="panelClasses"
+      @keydown.esc.stop.prevent="closeAndFocus"
+    >
+      <div class="gl-new-dropdown-inner">
+        <slot></slot>
+      </div>
+    </div>
+  </div>
+</template>

package/src/components/base/new_dropdowns/base_dropdown/constants.js

@@ -0,0 +1,2 @@
+export const FIXED_WIDTH_CLASS = '!gl-w-31';
+export const DEFAULT_OFFSET = 4;

package/src/components/base/new_dropdowns/constants.js

@@ -0,0 +1,20 @@
+// base dropdown events
+export const GL_DROPDOWN_SHOWN = 'shown';
+export const GL_DROPDOWN_HIDDEN = 'hidden';
+export const GL_DROPDOWN_BEFORE_CLOSE = 'beforeClose';
+export const GL_DROPDOWN_FOCUS_CONTENT = 'focusContent';
+
+// KEY Codes
+export const ARROW_DOWN = 'ArrowDown';
+export const ARROW_UP = 'ArrowUp';
+export const END = 'End';
+export const ENTER = 'Enter';
+export const HOME = 'Home';
+export const SPACE = 'Space';
+
+// Positioning strategies
+// https://floating-ui.com/docs/computePosition#strategy
+export const POSITION_ABSOLUTE = 'absolute';
+export const POSITION_FIXED = 'fixed';
+
+export const GL_DROPDOWN_CONTENTS_CLASS = 'gl-new-dropdown-contents';

package/src/components/base/new_dropdowns/disclosure/constants.js

@@ -0,0 +1,6 @@
+export const DISCLOSURE_DROPDOWN_ITEM_NAME = 'GlDisclosureDropdownItem';
+export const DISCLOSURE_DROPDOWN_GROUP_NAME = 'GlDisclosureDropdownGroup';
+export const DISCLOSURE_DROPDOWN_GROUP_BORDER_POSITIONS = {
+  top: 'top',
+  bottom: 'bottom',
+};

package/src/components/base/new_dropdowns/disclosure/disclosure_dropdown.md

@@ -0,0 +1,168 @@
+A disclosure dropdown is a button that toggles a panel containing a list of actions and/or links. Use
+[this decision tree](https://design.gitlab.com/components/dropdown-overview#which-component-should-you-use)
+to make sure this is the right dropdown component for you.
+
+## Basic usage
+
+```html
+<gl-disclosure-dropdown toggle-text="Actions" :items="items" />
+```
+
+## Icon-only disclosure dropdown
+
+Icon-only disclosure dropdowns must have an accessible name.
+You can provide this with the combination of `toggleText` and `textSrOnly` props.
+
+Optionally, you can use `no-caret` to remove the caret and `category="tertiary"` to remove the border.
+
+```html
+<gl-disclosure-dropdown
+  icon="ellipsis_v"
+  toggle-text="Actions"
+  text-sr-only
+  category="tertiary"
+  no-caret
+/>
+```
+
+## Opening the disclosure dropdown
+
+Disclosure dropdown will open on toggle button click (if it was previously closed).
+On open, `GlDisclosureDropdown` will emit the `shown` event.
+
+## Closing the disclosure dropdown
+
+The disclosure dropdown is closed by any of the following:
+
+- pressing <kbd>Esc</kbd>
+- clicking anywhere outside the component
+- clicking the action or link inside the dropdown
+
+Before closing, `GlDisclosureDropdown` emits a `beforeClose` event with these properties:
+
+1. `originalEvent` – the event that triggered closing of the dropdown
+2. `preventDefault` – a method which will prevent closing of the dropdown
+
+An example of using this event to prevent the dropdown from closing:
+
+```html
+<gl-disclosure-dropdown @beforeClose="$event.preventDefault()" />
+```
+
+Note that this method will also prevent the dropdown from closing even if the trigger button is clicked.
+
+You can use the `preventDefault` to filter out events that are causing undesired dropdown closing:
+
+```html
+<gl-disclosure-dropdown
+  @beforeClose="(e) => { ignoreElement.contains(e.originalEvent.target) && e.preventDefault() }"
+/>
+```
+
+After closing, `GlDisclosureDropdown` emits a `hidden` event.
+
+## Setting disclosure dropdown items
+
+Use the `items` prop to provide actions/links to the disclosure dropdown. Each
+item can be either an item or a group. For `Item`s, provide an `href` or `to` string to
+make them render as links. Otherwise, they will be buttons. Provide an `action`
+function to items to be called when they are pressed, or, listen for the
+`action` event on the top-level component. Both will receive the given item as
+an argument.
+A <!-- markdownlint-disable-next-line line-length -->
+[validation error](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/6cbff4f908b429cc01f17a4cc2868e881db1aa31/src/components/base/new_dropdowns/disclosure/utils.js#L1)
+will be triggered if neither field is set.
+
+Below are the expected shapes of these objects:
+
+```typescript
+type Item = {
+  // The item text
+  text: string;
+  // href link
+  href?: string;
+  // or, a Vue router link with `to`
+  to?: string;
+  // Item action
+  action?: (item: Item) => void;
+  // Set of extra attributes applied directly to the element
+  extraAttrs?: Object;
+  // Additional class/classes applied to the item wrapper
+  wrapperClass?: string;
+};
+
+type Group = {
+  // Name of the group, used as a header
+  name?: string;
+  // Items of the group
+  items: Array<Item>;
+  // Set of extra attributes applied directly to the element
+  extraAttrs?: Object;
+};
+
+type ItemsProp = Array<Item> | Array<Group>;
+```
+
+### Actions/links
+
+The `text` property is used to render the default disclosure dropdown item
+template. If you want to render a custom template for items, use the
+`list-item` scoped slot:
+
+```html
+<gl-disclosure-dropdown :items="items">
+  <template #list-item="{ item }">
+    <span class="gl-flex gl-items-center gl-justify-between">
+      {{item.text}}
+      <gl-icon v-if="item.icon" :name="item.icon" />
+    </span>
+  </template>
+</gl-disclosure-dropdown>
+```
+
+### Groups
+
+Actions/links can be contained within groups. A group can have a `name`
+property, which will be used as the group header if present.
+It also has a required property `items` that must be an array of links/actions.
+
+Groups can be at most one level deep: a group can only contain actions/links.
+Items and groups _cannot_ be siblings. Either all items are actions/links,
+or they are all groups.
+
+To render custom group labels, use the `group-label` scoped slot:
+
+```html
+<gl-disclosure-dropdown :items="groups">
+  <template #group-label="{ group }">
+    {{ group.name }} <gl-badge size="sm">{{ group.items.length }}</gl-badge>
+  </template>
+</gl-disclosure-dropdown>
+```
+
+To draw a horizontal line that separates two groups, set the `bordered` property.
+By default, the border appears above the group. You can change the border position
+using the `border-position` property:
+
+```html
+<gl-disclosure-dropdown>
+  <gl-disclosure-dropdown-group bordered border-position="bottom" :group="group" />
+</gl-disclosure-dropdown>
+```
+
+### Miscellaneous content
+
+Besides default components, disclosure dropdown can render miscellaneous content inside it.
+In this case the user is responsible for handling all events and navigation inside the disclosure.
+
+### Dealing with long option texts
+
+- Some options might have long non-wrapping text that would overflow the dropdown maximum width. In
+  such cases, it's recommended to override the `#list-item` slot and to truncate the option text using
+  `GlTruncate`.
+- If the toggle text reflects the selected option text, it might be necessary to truncate
+  it too by overriding the `#toggle` slot.
+
+## Split dropdown
+
+See [button group documentation](/docs/base-button-group--docs#split-dropdowns).