@gitlab/duo-ui 0.1.0

package/src/components/base/form/input_group_text/input_group_text.vue

@@ -0,0 +1,17 @@
+<script>
+import { BInputGroupText } from '../../../../vendor/bootstrap-vue/src/components/input-group/input-group-text';
+
+export default {
+  name: 'GlInputGroupText',
+  components: {
+    BInputGroupText,
+  },
+  inheritAttrs: false,
+};
+</script>
+
+<template>
+  <b-input-group-text v-bind="$attrs" v-on="$listeners">
+    <slot></slot>
+  </b-input-group-text>
+</template>

package/src/components/base/icon/icon.md

@@ -0,0 +1,27 @@
+## Usage
+
+The Icon component can be used to render any svg within the @gitlab/svgs icon sprites.
+
+### Accessibility
+
+`gl-icon` icons are hidden from screen readers by default, as usages of icons are commonly decorative.
+
+If the icon is not decorative, add an `aria-label` attribute to `gl-icon` to give it an accessible name.
+This label is read out by screen readers.
+
+If the icon is clickable, use `gl-button` instead of `gl-icon` because a clickable element should
+semantically be a button.
+
+```html
+<!-- icon, which is hidden from screen readers by default  -->
+<gl-icon name="rocket" />
+
+<!-- icon, which has an accessible name "Confidential issue" that is read out by screen readers -->
+<gl-icon name="eye-slash" :aria-label="__('Confidential issue')" />
+
+<!-- clickable icon, which is borderless and padding-less -->
+<gl-button icon="close" category="tertiary" class="!gl-p-0" aria-label="Close" />
+```
+
+For more information about icons within GitLab, visit the
+[GitLab accessibility guidelines](https://docs.gitlab.com/ee/development/fe_guide/accessibility#icons).

package/src/components/base/icon/icon.scss

@@ -0,0 +1,8 @@
+.gl-icon {
+  @each $size in $gl-icon-sizes {
+    &.s#{$size} {
+      width: #{$size}px;
+      height: #{$size}px;
+    }
+  }
+}

package/src/components/base/icon/icon.vue

@@ -0,0 +1,98 @@
+<!-- eslint-disable vue/multi-word-component-names -->
+<script>
+import iconsPath from '@gitlab/svgs/dist/icons.svg';
+import { iconSizeOptions, iconVariantOptions } from '../../../utils/constants';
+
+let iconValidator = () => true;
+
+/*
+ During development/tests we want to validate that we are just using icons that are actually defined
+*/
+if (process.env.NODE_ENV !== 'production') {
+  // eslint-disable-next-line global-require
+  const data = require('@gitlab/svgs/dist/icons.json');
+  const { icons } = data;
+  iconValidator = (value) => {
+    if (icons.includes(value)) {
+      return true;
+    }
+    // eslint-disable-next-line no-console
+    console.warn(`Icon '${value}' is not a known icon of @gitlab/svgs`);
+    return false;
+  };
+}
+
+/** This is a re-usable vue component for rendering a svg sprite icon
+ *  @example
+ *  <icon
+ *    name="retry"
+ *    :size="32"
+ *    class="top"
+ *  />
+ */
+export default {
+  name: 'GlIcon',
+  props: {
+    /**
+     * Accessible icon name used by screen readers and other assistive technologies.
+     * Provide when icon is not merely decorative
+     */
+    ariaLabel: {
+      type: String,
+      required: false,
+      default: undefined,
+    },
+    /**
+     * One of the icons from https://gitlab-org.gitlab.io/gitlab-svgs/ project
+     */
+    name: {
+      type: String,
+      required: true,
+      validator: iconValidator,
+    },
+    /**
+     * Icon size
+     */
+    size: {
+      type: Number,
+      required: false,
+      default: 16,
+      validator: (value) => iconSizeOptions.includes(value),
+    },
+    /**
+     * Icon variant
+     */
+    variant: {
+      type: String,
+      required: false,
+      default: 'current',
+      validator: (value) => Object.keys(iconVariantOptions).includes(value),
+    },
+  },
+  computed: {
+    spriteHref() {
+      return `${iconsPath}#${this.name}`;
+    },
+    iconSizeClass() {
+      return this.size ? `s${this.size}` : '';
+    },
+    iconVariantClass() {
+      return this.variant ? iconVariantOptions[this.variant] : '';
+    },
+  },
+};
+</script>
+
+<template>
+  <svg
+    :key="spriteHref"
+    :class="['gl-icon', iconSizeClass, iconVariantClass]"
+    :data-testid="`${name}-icon`"
+    role="img"
+    :aria-hidden="!ariaLabel"
+    :aria-label="ariaLabel"
+    v-on="$listeners"
+  >
+    <use :href="spriteHref" />
+  </svg>
+</template>

package/src/components/base/infinite_scroll/infinite_scroll.md

@@ -0,0 +1,104 @@
+## Usage
+
+The infinite scroll component wraps around a results list and emits a message
+(`bottomReached`) when the bottom of the viewport is reached, which should trigger
+a re-fetching. The `gl-infinite-scroll` component expects its parent component to
+manage the re-fetching.
+
+Additionally it emits a `topReached` message when the top of the viewport is reached, which
+can be useful to load items on top of the available data. If only `topReached` is present, the
+viewport will be scrolled to the bottom the first time this component is mounted.
+
+## Public methods
+
+Useful public methods you can call via `$refs`:
+
+- `.scrollUp()`: Scrolls to the top of the container.
+- `.scrollDown()`: Scrolls to the bottom of the container.
+- `.scrollTo({ top, behavior })`: Scrolls to a number of pixels
+  along the Y axis of the container. The scrolling behavior can also be specified,
+  as per MDN spec (<https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollTo>)
+
+## Implementation Example
+
+This is how a full implementation would look like with paginated results from GitLab's
+`projects` API.
+
+In the component's state, initialize a `pageInfo` object:
+
+```js
+pageInfo: {
+  currentPage: 0,
+  nextPage: 0,
+  totalPages: 0,
+  totalResults: 0,
+}
+```
+
+When fetching for the first time, set the state with the header
+information in the mutations:
+
+```html
+Vue.set(state.pageInfo, 'currentPage', parseInt(headers['X-Page'], 10));
+Vue.set(state.pageInfo, 'nextPage', parseInt(headers['X-Next-Page'], 10));
+Vue.set(state.pageInfo, 'totalPages', parseInt(headers['X-Total-Pages'], 10));
+Vue.set(state.pageInfo, 'totalResults', parseInt(headers['X-Total'], 10));
+```
+
+_Note: There is a function you can use for parsing integers in headers in
+GitLab called `parseIntPagination` in `common/utils.js`_
+
+Every time `bottomReached` happens, update the state in your mutations:
+
+```js
+state.searchResults = state.searchResults.concat(results.data);
+Vue.set(state.pageInfo, 'nextPage', parseInt(headers['X-Next-Page'],10));
+Vue.set(state.pageInfo, 'totalPages', parseInt(headers['X-Total-Pages'],10));
+```
+
+Use the state to fetch the next page in the actions. In this case, the `Projects`
+API allows us to send in a `page` parameter to fetch a certain page from the
+list of results.
+
+```js
+export const fetchNextPage = ({ state, dispatch }) => {
+  if(state.pageInfo.currentPage < state.pageInfo.totalPages) {
+    Api.projects(searchQuery, { page: state.pageInfo.nextPage })
+      ...
+  }
+};
+```
+
+```html
+<script>
+exportDefault {
+  components: {
+    GlInfiniteScroll,
+  },
+  computed: {
+    ...mapState([
+      'pageInfo',
+      'searchResults',
+    ]),
+  },
+  methods: {
+    ...mapActions([
+      'fetchNextPage',
+    ]),
+    bottomReached() {
+      this.fetchNextPage();
+    },
+  },
+}
+</script>
+<template>
+  <gl-infinite-scroll
+    @bottomReached="bottomReached"
+    :max-list-height="400"
+    :fetched-items="searchResults.length"
+    :total-items="totalResults"
+  >
+    ...Results in a list, another component, etc ....
+  </gl-infinite-scroll>
+</template>
+```

package/src/components/base/infinite_scroll/infinite_scroll.scss

@@ -0,0 +1,11 @@
+.gl-infinite-scroll-container {
+  @apply gl-overflow-x-hidden;
+  @apply gl-overflow-y-auto;
+  @apply gl-text-base;
+}
+
+.gl-infinite-scroll-legend {
+  @apply gl-text-center;
+  @apply gl-text-sm;
+  @apply gl-text-gray-900;
+}

package/src/components/base/infinite_scroll/infinite_scroll.vue

@@ -0,0 +1,169 @@
+<script>
+import throttle from 'lodash/throttle';
+
+const throttleDuration = 1000;
+/**
+ * After adding more items, scroll will adjust slightly.
+ * Values in pixels, should be a small amount.
+ */
+export const adjustScrollGap = 5;
+const THRESHOLD = 1;
+
+export default {
+  name: 'GlInfiniteScroll',
+  props: {
+    /**
+     * Total number of items available
+     */
+    totalItems: {
+      type: Number,
+      required: false,
+      default: 0,
+    },
+    /**
+     * Numbers of items fetched before scrolling
+     */
+    fetchedItems: {
+      type: Number,
+      required: true,
+    },
+    /**
+     * Max height of the list before the scrollbar appears
+     */
+    maxListHeight: {
+      type: Number,
+      required: false,
+      default: 0,
+    },
+  },
+  computed: {
+    listHeight() {
+      return {
+        maxHeight: this.maxListHeight ? `${this.maxListHeight}px` : 'auto',
+      };
+    },
+    legendText() {
+      if (this.totalItems > 0) {
+        return `Showing ${this.fetchedItems} of ${this.totalItems} items`;
+      }
+
+      return `Showing ${this.fetchedItems} items`;
+    },
+  },
+  watch: {
+    fetchedItems(newVal, oldVal) {
+      // Re-adjust scroll to the current item if more items are added
+      if (newVal > oldVal) {
+        const { scrollHeight, scrollTop } = this.$refs.infiniteContainer;
+        // Only when scrolled to the top
+        if (scrollHeight !== 0 && scrollTop === 0) {
+          // Wait until the DOM is fully updated to adjust scroll
+          this.$nextTick(() => {
+            const { scrollHeight: newScrollHeight } = this.$refs.infiniteContainer;
+
+            // New scrollTop is the new height, minus the old height
+            // minus a small space to allow the user to trigger a scroll once more
+            let top = newScrollHeight - scrollHeight - adjustScrollGap;
+
+            // Never adjust to 0, or a new event may be be triggered
+            if (top < 1) {
+              top = 1;
+            }
+
+            this.scrollTo({ top });
+          });
+        }
+      }
+    },
+  },
+
+  mounted() {
+    // Scroll to bottom for reverse effect
+    this.$nextTick(() => {
+      if (this.$listeners.topReached && !this.$listeners.bottomReached) {
+        this.scrollDown();
+      }
+    });
+  },
+
+  methods: {
+    /**
+     * Scroll to the top of the container, leaving a gap
+     * to avoid triggering the event.
+     */
+    scrollUp() {
+      this.scrollTo({ top: adjustScrollGap });
+    },
+    /**
+     * Scroll to the bottom of the container, leaving a gap
+     * to avoid triggering the event.
+     */
+    scrollDown() {
+      const { scrollHeight } = this.$refs.infiniteContainer;
+      this.scrollTo({ top: scrollHeight - adjustScrollGap });
+    },
+    /**
+     * Scroll to a location in the container
+     *
+     * @param params.top - Number of pixels along Y axis to
+     * scroll the list container.
+     * @param params.behavior - Determines whether scrolling
+     * is instant or animates smoothly. Can be 'auto', 'instant', or 'smooth'
+     * See [MDN spec](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollTo)
+     */
+    scrollTo({ top, behavior }) {
+      this.$refs.infiniteContainer.scrollTo({ top, behavior });
+    },
+
+    topReached: throttle(function topReachedThrottled() {
+      /**
+       * Emitted when item container is scrolled to the top
+       */
+      this.$emit('topReached');
+    }, throttleDuration),
+    bottomReached: throttle(function bottomReachedThrottled() {
+      /**
+       * Emitted when item container is scrolled to the bottom
+       */
+      this.$emit('bottomReached');
+    }, throttleDuration),
+    itemsListHeight() {
+      return this.$refs.infiniteContainer.scrollHeight;
+    },
+    scrollTop() {
+      return this.$refs.infiniteContainer.scrollTop;
+    },
+    handleScroll: throttle(function handleScrollThrottled() {
+      if (Math.abs(this.itemsListHeight() - this.maxListHeight - this.scrollTop()) < THRESHOLD) {
+        this.bottomReached();
+      } else if (this.scrollTop() <= THRESHOLD) {
+        this.topReached();
+      }
+    }),
+  },
+};
+</script>
+
+<template>
+  <div>
+    <!-- @slot Header of the list, appears above the items -->
+    <slot name="header"></slot>
+    <div
+      ref="infiniteContainer"
+      :style="listHeight"
+      class="gl-infinite-scroll-container"
+      v-bind="$attrs"
+      @scroll="handleScroll"
+      v-on="$listeners"
+    >
+      <!-- @slot List of items -->
+      <slot name="items"></slot>
+    </div>
+    <p class="gl-infinite-scroll-legend">
+      <!-- @slot Footer of the list, appears below the items -->
+      <slot :fetched-items="fetchedItems" :total-items="totalItems">
+        {{ legendText }}
+      </slot>
+    </p>
+  </div>
+</template>

package/src/components/base/keyset_pagination/keyset_pagination.md

@@ -0,0 +1,49 @@
+Pagination is used to help users parse a large number of items on a page,
+whenever there are too many results to show at once. Pagination breaks up
+results into several pages with controls for navigating forward and backward, or
+to a specific page.
+
+## Usage
+
+The simplest way to use `GlKeysetPagination` with a paginated GraphQL response
+is to `v-bind` to the
+[`PageInfo`](https://docs.gitlab.com/ee/api/graphql/reference/#pageinfo) type
+returned by the endpoint:
+
+```html
+<gl-keyset-pagination v-bind="pageInfo" />
+```
+
+This is possible because the default field names of the `PageInfo` type align
+with the `props` of this component.
+
+## Dos and don'ts
+
+**✅ Do** provide the `prevText` and `nextText` props with translatable strings.
+The default strings ("Prev" and "Next") are hardcoded in this component and
+can't be translated.
+
+Example:
+
+```html
+<gl-keyset-pagination v-bind="pageInfo" :prev-text="__('Prev')" :next-text="__('Next')" />
+```
+
+**✅ Do** use this component for paginating GraphQL requests[^1] (or any
+endpoint that uses keyset pagination).
+
+**❌ Don't** use this component for paginating REST requests[^1] (or any
+endpoint that uses offset pagination).
+
+For offset pagination, use the [`GlPagination`
+component](/?path=/story/base-pagination--default) instead.
+
+For more information on the difference between offset and keyset pagination see
+[our documentation on GraphQL
+pagination](https://docs.gitlab.com/ee/development/graphql_guide/pagination.html).
+
+[^1]: There's no intrinsic reason why GraphQL endpoints can't support offset pagination (in fact, [the official documentation](https://graphql.org/learn/pagination/#pagination-and-edges) shows an example offset pagination implementation) or why REST endpoints can't support keyset pagination. This is simply how we've chosen to implement our REST and GraphQL endpoints at GitLab.
+
+## Pajamas reference
+
+<https://design.gitlab.com/components/pagination>

package/src/components/base/keyset_pagination/keyset_pagination.scss

@@ -0,0 +1,9 @@
+.gl-keyset-pagination {
+  // See https://gitlab.com/gitlab-org/gitlab-ui/-/merge_requests/1487
+  // for the reasoning behind the double .gl-button.gl-button
+  .gl-button.gl-button {
+    .gl-icon {
+      @apply gl-m-0;
+    }
+  }
+}

package/src/components/base/keyset_pagination/keyset_pagination.vue

@@ -0,0 +1,152 @@
+<script>
+import GlButton from '../button/button.vue';
+import GlButtonGroup from '../button_group/button_group.vue';
+import GlIcon from '../icon/icon.vue';
+import { translate } from '../../../utils/i18n';
+
+export default {
+  name: 'GlKeysetPagination',
+  components: {
+    GlButtonGroup,
+    GlButton,
+    GlIcon,
+  },
+  inheritAttrs: false,
+  props: {
+    // The following 4 properties match the default names of the
+    // [PageInfo](https://docs.gitlab.com/ee/api/graphql/reference/index.html#pageinfo)
+    // GraphQL type, allowing the returned `pageInfo` object to
+    // be bound directly to this component:
+    // `<gl-keyset-pagination v-bind="pageInfo">`
+    /**
+     * Whether or not the "Prev" button should be enabled
+     */
+    hasPreviousPage: {
+      type: Boolean,
+      required: false,
+      default: false,
+    },
+    /**
+     * Whether or not the "Next" button should be enabled
+     */
+    hasNextPage: {
+      type: Boolean,
+      required: false,
+      default: false,
+    },
+    /**
+     * A cursor that points to the first item in the current page.
+     * Will be passed as an event parameter when the "prev" event is fired.
+     */
+    startCursor: {
+      type: String,
+      required: false,
+      default: null,
+    },
+    /**
+     * A cursor that points to the last item in the current page.
+     * Will be passed as an event parameter when the "next" event is fired.
+     */
+    endCursor: {
+      type: String,
+      required: false,
+      default: null,
+    },
+    /**
+     * The text that will be rendered inside the "Previous" button.
+     * It's important to provide this parameter since the default text is not translatable.
+     */
+    prevText: {
+      type: String,
+      required: false,
+      default: () => translate('GlKeysetPagination.prevText', 'Previous'),
+    },
+    /**
+     * A link that will be used as the "Prev" button\'s "href" attribute.
+     * If provided, the "Prev" button renders as a link button; otherwise, it is rendered as a regular button.
+     */
+    prevButtonLink: {
+      type: String,
+      required: false,
+      default: null,
+    },
+    /**
+     * The aria-label that needs to be set for the
+     * pagination landmark region.
+     */
+    navigationLabel: {
+      type: String,
+      required: false,
+      default: () => translate('GlKeysetPagination.navigationLabel', 'Pagination'),
+    },
+    /**
+     * The text that will be rendered inside the "Next" button.
+     * It's important to provide this parameter since the default text is not translatable.
+     */
+    nextText: {
+      type: String,
+      required: false,
+      default: () => translate('GlKeysetPagination.nextText', 'Next'),
+    },
+    /**
+     * A link that will be used as the "Next" button\'s "href" attribute.
+     * If provided, the "Next" button renders as a link button; otherwise, it is rendered as a regular button.
+     */
+    nextButtonLink: {
+      type: String,
+      required: false,
+      default: null,
+    },
+    /**
+     * Whether or not both buttons should be disabled (regardless of the "hasPreviousPage" and "hasNextPage" values).
+     */
+    disabled: {
+      type: Boolean,
+      required: false,
+      default: false,
+    },
+  },
+  computed: {
+    isVisible() {
+      return this.hasPreviousPage || this.hasNextPage;
+    },
+  },
+};
+</script>
+
+<template>
+  <nav v-if="isVisible" class="gl-pagination" :aria-label="navigationLabel">
+    <gl-button-group class="gl-keyset-pagination" v-bind="$attrs" v-on="$listeners">
+      <gl-button
+        :href="prevButtonLink"
+        :disabled="disabled || !hasPreviousPage"
+        data-testid="prevButton"
+        category="tertiary"
+        @click="$emit('prev', startCursor)"
+      >
+        <!-- @slot Used to customize the appearance of the "Prev" button -->
+        <slot name="previous-button-content">
+          <div class="gl-align-center gl-flex">
+            <gl-icon name="chevron-left" />
+            {{ prevText }}
+          </div>
+        </slot>
+      </gl-button>
+      <gl-button
+        :href="nextButtonLink"
+        :disabled="disabled || !hasNextPage"
+        data-testid="nextButton"
+        category="tertiary"
+        @click="$emit('next', endCursor)"
+      >
+        <!-- @slot Used to customize the appearance of the "Next" button -->
+        <slot name="next-button-content">
+          <div class="gl-align-center gl-flex">
+            {{ nextText }}
+            <gl-icon name="chevron-right" />
+          </div>
+        </slot>
+      </gl-button>
+    </gl-button-group>
+  </nav>
+</template>

package/src/components/base/label/label.md

@@ -0,0 +1,15 @@
+Labels are editable objects that allow users to manually categorize other objects, like issues,
+merge requests, and epics. They have a name, description, and a customizable background color.
+They provide a quick way to recognize which categories the labeled object belongs to.
+
+## Using the component
+
+```js
+<gl-label
+  background-color="#D9C2EE"
+  title="Label content"
+  description="Some content"
+  tooltipPlacement="top"
+  target="http://some.url"
+/>
+```