@gitlab/ui 32.43.3 → 32.46.0

package/src/components/base/paginated_list/__snapshots__/paginated_list.spec.js.snap

@@ -37,7 +37,7 @@ exports[`Paginated List Pagination renders 1 item on page 7 with page size of 2
     labelfirstpage="Go to first page"
     labellastpage="Go to last page"
     labelnextpage="Go to next page"
-    labelpage="page => \`Go to page \${page}\`"
+    labelpage="[Function]"
     labelprevpage="Go to previous page"
     limits="[object Object]"
     nexttext="Next"
@@ -114,7 +114,7 @@ exports[`Paginated List Pagination renders 3 items on page 2 with default page s
     labelfirstpage="Go to first page"
     labellastpage="Go to last page"
     labelnextpage="Go to next page"
-    labelpage="page => \`Go to page \${page}\`"
+    labelpage="[Function]"
     labelprevpage="Go to previous page"
     limits="[object Object]"
     nexttext="Next"
@@ -217,7 +217,7 @@ exports[`Paginated List Pagination renders 5 items on page 1 for a page size of
     labelfirstpage="Go to first page"
     labellastpage="Go to last page"
     labelnextpage="Go to next page"
-    labelpage="page => \`Go to page \${page}\`"
+    labelpage="[Function]"
     labelprevpage="Go to previous page"
     limits="[object Object]"
     nexttext="Next"
@@ -385,7 +385,7 @@ exports[`Paginated List Pagination renders 10 items for a default page size of 1
     labelfirstpage="Go to first page"
     labellastpage="Go to last page"
     labelnextpage="Go to next page"
-    labelpage="page => \`Go to page \${page}\`"
+    labelpage="[Function]"
     labelprevpage="Go to previous page"
     limits="[object Object]"
     nexttext="Next"
@@ -592,7 +592,7 @@ exports[`Paginated List Pagination renders 13 items for a default page size of 2
     labelfirstpage="Go to first page"
     labellastpage="Go to last page"
     labelnextpage="Go to next page"
-    labelpage="page => \`Go to page \${page}\`"
+    labelpage="[Function]"
     labelprevpage="Go to previous page"
     limits="[object Object]"
     nexttext="Next"
@@ -712,7 +712,7 @@ exports[`Paginated List Search states renders the list filtered by search result
     labelfirstpage="Go to first page"
     labellastpage="Go to last page"
     labelnextpage="Go to next page"
-    labelpage="page => \`Go to page \${page}\`"
+    labelpage="[Function]"
     labelprevpage="Go to previous page"
     limits="[object Object]"
     nexttext="Next"
@@ -832,7 +832,7 @@ exports[`Paginated List Searchless states renders the list with nested items, wh
     labelfirstpage="Go to first page"
     labellastpage="Go to last page"
     labelnextpage="Go to next page"
-    labelpage="page => \`Go to page \${page}\`"
+    labelpage="[Function]"
     labelprevpage="Go to previous page"
     limits="[object Object]"
     nexttext="Next"
@@ -883,7 +883,7 @@ exports[`Paginated List props filter filters on default "id" key 1`] = `
     labelfirstpage="Go to first page"
     labellastpage="Go to last page"
     labelnextpage="Go to next page"
-    labelpage="page => \`Go to page \${page}\`"
+    labelpage="[Function]"
     labelprevpage="Go to previous page"
     limits="[object Object]"
     nexttext="Next"
@@ -934,7 +934,7 @@ exports[`Paginated List props filter filters on provided "myKey" key 1`] = `
     labelfirstpage="Go to first page"
     labellastpage="Go to last page"
     labelnextpage="Go to next page"
-    labelpage="page => \`Go to page \${page}\`"
+    labelpage="[Function]"
     labelprevpage="Go to previous page"
     limits="[object Object]"
     nexttext="Next"
@@ -985,7 +985,7 @@ exports[`Paginated List props filter filters with provided filter function 1`] =
     labelfirstpage="Go to first page"
     labellastpage="Go to last page"
     labelnextpage="Go to next page"
-    labelpage="page => \`Go to page \${page}\`"
+    labelpage="[Function]"
     labelprevpage="Go to previous page"
     limits="[object Object]"
     nexttext="Next"

package/src/components/base/pagination/pagination.documentation.js

@@ -1,106 +1,6 @@
-import examples from './examples';
 import description from './pagination.md';
 
 export default {
   followsDesignSystem: true,
   description,
-  examples,
-  propsInfo: {
-    perPage: {
-      additionalInfo: 'Number of items per page',
-    },
-    totalItems: {
-      additionalInfo: 'Total number of items',
-    },
-    limits: {
-      additionalInfo: 'The object must contain the xs, sm, md and default keys',
-    },
-    linkGen: {
-      additionalInfo:
-        'A function that receives the page number and that returns a string representing the page URL',
-    },
-    prevPage: {
-      additionalInfo:
-        'When using the compact pagination, use this prop to pass the previous page number',
-    },
-    prevText: {
-      additionalInfo: 'Text for the previous button (overridden by "previous" slot)',
-    },
-    nextPage: {
-      additionalInfo:
-        'When using the compact pagination, use this prop to pass the next page number',
-    },
-    nextText: {
-      additionalInfo: 'Text for the next button (overridden by "next" slot)',
-    },
-    ellipsisText: {
-      additionalInfo:
-        'Text for the ellipsis (overridden by "ellipsis-left" and "ellipsis-right" slots)',
-    },
-    labelFirstPage: {
-      additionalInfo: 'aria-label for the first page item',
-    },
-    labelPrevPage: {
-      additionalInfo: 'aria-label for the previous page item',
-    },
-    labelNextPage: {
-      additionalInfo: 'aria-label for the next page item',
-    },
-    labelLastPage: {
-      additionalInfo: 'aria-label for the last page item',
-    },
-    labelPage: {
-      additionalInfo:
-        'aria-label getter for numbered page items, defaults to "Go to page <page_number>"',
-    },
-    align: {
-      additionalInfo:
-        'Controls the component\'s horizontal alignment, value should be one of "left", "center", "right" or "fill"',
-    },
-  },
-  events: [
-    {
-      event: 'input',
-      description: 'Emitted when the page changes',
-      args: [
-        {
-          arg: 'value',
-          description: 'The page that just got loaded',
-        },
-      ],
-    },
-    {
-      event: 'next',
-      description: 'Emitted when the "next" button is clicked',
-    },
-    {
-      event: 'previous',
-      description: 'Emitted when the "previous" button is clicked',
-    },
-  ],
-  slots: [
-    {
-      name: 'previous',
-      description: `Content for the "previous" button. Overrides the "prevText" prop.`,
-      scopedProps: `{ active: boolean, disabled: boolean, page: number }`,
-    },
-    {
-      name: 'next',
-      description: `Content for the "next" button. Overrides the "nextText" prop.`,
-      scopedProps: `{ active: boolean, disabled: boolean, page: number }`,
-    },
-    {
-      name: 'page-number',
-      description: `Content for page number buttons.`,
-      scopedProps: `{ active: boolean, disabled: boolean, page: number }`,
-    },
-    {
-      name: 'ellipsis-left',
-      description: `Content for the left ellipsis. Overrides the "ellipsisText" prop.`,
-    },
-    {
-      name: 'ellipsis-right',
-      description: `Content for the right ellipsis. Overrides the "ellipsisText" prop.`,
-    },
-  ],
 };

package/src/components/base/pagination/pagination.md

@@ -1,18 +1,14 @@
-# Pagination
-
-<!-- STORY -->
-
 ## Current page
 
 The current page's value should be bound using `v-model`, e.g.:
 
 ```html
 <script>
-export default {
-  data: () => ({
-    page: 2,
-  }),
-};
+  export default {
+    data: () => ({
+      page: 2,
+    }),
+  };
 </script>
 
 <template>

package/src/components/base/pagination/pagination.spec.js

@@ -1,12 +1,10 @@
-import { mount, createLocalVue } from '@vue/test-utils';
+import { mount } from '@vue/test-utils';
 import debounce from 'lodash/debounce';
 import Pagination from './pagination.vue';
 import { breakpoints } from '~/utils/breakpoints';
 
 jest.mock('lodash/debounce', () => jest.fn((fn) => fn));
 
-const localVue = createLocalVue();
-
 const expectClassActive = expect.arrayContaining(['active']);
 const mockResizeWidth = (width) => {
   window.innerWidth = width;
@@ -29,7 +27,6 @@ describe('pagination component', () => {
         itemsPerPage: 20,
         ...props,
       },
-      localVue,
       ...options,
     });
   };

package/src/components/base/pagination/pagination.stories.js

@@ -1,41 +1,19 @@
-import { withKnobs, number, text, boolean } from '@storybook/addon-knobs';
-import { documentedStoriesOf } from '../../../../documentation/documented_stories';
 import { alignOptions } from '../../../utils/constants';
 import readme from './pagination.md';
 import GlPagination from './pagination.vue';
 
-const components = {
-  GlPagination,
-};
-
-function generateBaseProps() {
-  return {
-    prevText: {
-      default: text('Prev button text', 'Prev'),
-    },
-    nextText: {
-      default: text('Next button text', 'Next'),
-    },
-    disabled: {
-      default: boolean('Disabled', false),
-    },
-  };
-}
+const generateBaseProps = ({ prevText = 'Prev', nextText = 'Next', disabled = false } = {}) => ({
+  prevText,
+  nextText,
+  disabled,
+});
 
-function generateFullProps({ page = 3, perPage = 10, totalItems = 200 } = {}) {
-  return {
-    initialPage: {
-      default: number('current page', page),
-    },
-    perPage: {
-      default: number('per page', perPage),
-    },
-    totalItems: {
-      default: number('total items', totalItems),
-    },
-    ...generateBaseProps(),
-  };
-}
+const generateFullProps = ({ page = 3, perPage = 10, totalItems = 200 } = {}) => ({
+  initialPage: page,
+  perPage,
+  totalItems,
+  ...generateBaseProps(),
+});
 
 const defaults = {
   data() {
@@ -51,13 +29,10 @@ const defaults = {
   },
 };
 
-documentedStoriesOf('base/pagination', readme)
-  .addDecorator(withKnobs)
-  .add('default', () => ({
-    props: generateFullProps(),
-    ...defaults,
-    components,
-    template: `<gl-pagination
+export const Default = (args, { argTypes }) => ({
+  props: Object.keys(argTypes),
+  ...defaults,
+  template: `<gl-pagination
       v-model="page"
       :per-page="perPage"
       :total-items="totalItems"
@@ -65,84 +40,101 @@ documentedStoriesOf('base/pagination', readme)
       :next-text="nextText"
       :disabled="disabled"
       />`,
-  }))
-  .add('compact', () => ({
-    ...defaults,
-    data() {
-      return {
-        page: 1,
-        alignOptions,
-      };
+});
+Default.args = generateFullProps();
+
+export const Compact = () => ({
+  ...defaults,
+  props: generateFullProps(),
+  data() {
+    return {
+      page: 1,
+      alignOptions,
+    };
+  },
+  computed: {
+    prevPage() {
+      return Math.max(this.page - 1, 0);
     },
-    props: generateBaseProps(),
-    components,
-    computed: {
-      prevPage() {
-        return Math.max(this.page - 1, 0);
-      },
-      nextPage() {
-        const nextPage = this.page + 1;
-        return nextPage > 3 ? 0 : nextPage;
-      },
+    nextPage() {
+      const nextPage = this.page + 1;
+      return nextPage > 3 ? 0 : nextPage;
     },
-    template: `
-    <div class="text-center gl-font-base">
-      <gl-pagination
-        v-model="page"
-        :prev-page="prevPage"
-        :next-page="nextPage"
-        :prev-text="prevText"
-        :next-text="nextText"
-        :disabled="disabled"
-        :align="alignOptions.center"
-      />
-      Page {{ page }} of 3
-    </div>`,
-  }))
-  .add('link based', () => ({
-    props: generateFullProps(),
-    ...defaults,
-    components,
-    methods: {
-      linkGen(page) {
-        return `/page/${page}`;
+  },
+  template: `
+      <div class="text-center gl-font-base">
+        <gl-pagination
+          v-model="page"
+          :prev-page="prevPage"
+          :next-page="nextPage"
+          :prev-text="prevText"
+          :next-text="nextText"
+          :disabled="disabled"
+          :align="alignOptions.center"
+        />
+        Page {{ page }} of 3
+      </div>`,
+});
+
+export const LinkBased = (args, { argTypes }) => ({
+  props: Object.keys(argTypes),
+  ...defaults,
+  methods: {
+    linkGen(page) {
+      return `/page/${page}`;
+    },
+  },
+  template: `<gl-pagination
+    v-model="page"
+    :per-page="perPage"
+    :total-items="totalItems"
+    :prev-text="prevText"
+    :next-text="nextText"
+    :disabled="disabled"
+    :link-gen="linkGen"
+    />`,
+});
+LinkBased.args = generateFullProps();
+
+export const AlignCenter = (args, { argTypes }) => ({
+  props: Object.keys(argTypes),
+  ...defaults,
+  template: `<gl-pagination
+    v-model="page"
+    :per-page="perPage"
+    :total-items="totalItems"
+    :prev-text="prevText"
+    :next-text="nextText"
+    :disabled="disabled"
+    :align="alignOptions.center"
+    />`,
+});
+AlignCenter.args = generateFullProps();
+
+export const AlignRight = (args, { argTypes }) => ({
+  props: Object.keys(argTypes),
+  ...defaults,
+  template: `<gl-pagination
+    v-model="page"
+    :per-page="perPage"
+    :total-items="totalItems"
+    :prev-text="prevText"
+    :next-text="nextText"
+    :disabled="disabled"
+    :align="alignOptions.right"
+    />`,
+});
+AlignRight.args = generateFullProps();
+
+export default {
+  title: 'base/pagination',
+  component: GlPagination,
+  parameters: {
+    knobs: { disable: true },
+    docs: {
+      description: {
+        component: readme,
       },
     },
-    template: `<gl-pagination
-      v-model="page"
-      :per-page="perPage"
-      :total-items="totalItems"
-      :prev-text="prevText"
-      :next-text="nextText"
-      :disabled="disabled"
-      :link-gen="linkGen"
-      />`,
-  }))
-  .add('align center', () => ({
-    props: generateFullProps(),
-    ...defaults,
-    components,
-    template: `<gl-pagination
-      v-model="page"
-      :per-page="perPage"
-      :total-items="totalItems"
-      :prev-text="prevText"
-      :next-text="nextText"
-      :disabled="disabled"
-      :align="alignOptions.center"
-      />`,
-  }))
-  .add('align right', () => ({
-    props: generateFullProps(),
-    ...defaults,
-    components,
-    template: `<gl-pagination
-      v-model="page"
-      :per-page="perPage"
-      :total-items="totalItems"
-      :prev-text="prevText"
-      :next-text="nextText"
-      :disabled="disabled"
-      :align="alignOptions.right"
-      />`,
-  }));
+  },
+};

package/src/components/base/pagination/pagination.vue

@@ -26,17 +26,26 @@ export default {
       default: 1,
       validator: (x) => x > 0,
     },
+    /**
+     * Number of items per page
+     */
     perPage: {
       type: Number,
       required: false,
       default: 20,
       validator: (x) => x > 0,
     },
+    /**
+     * Total number of items
+     */
     totalItems: {
       type: Number,
       required: false,
       default: 0,
     },
+    /**
+     * The object must contain the xs, sm, md and default keys
+     */
     limits: {
       type: Object,
       required: false,
@@ -51,61 +60,97 @@ export default {
         return missingSizes === 0 ? true : value.default;
       },
     },
+    /**
+     * A function that receives the page number and that returns a string representing the page URL
+     */
     linkGen: {
       type: Function,
       required: false,
       default: null,
     },
+    /**
+     * When using the compact pagination, use this prop to pass the previous page number
+     */
     prevPage: {
       type: Number,
       required: false,
       default: null,
     },
+    /**
+     * Text for the previous button (overridden by "previous" slot)
+     */
     prevText: {
       type: String,
       required: false,
       default: 'Prev',
     },
+    /**
+     * When using the compact pagination, use this prop to pass the next page number
+     */
     nextPage: {
       type: Number,
       required: false,
       default: null,
     },
+    /**
+     * Text for the next button (overridden by "next" slot)
+     */
     nextText: {
       type: String,
       required: false,
       default: 'Next',
     },
+    /**
+     * Text for the ellipsis (overridden by "ellipsis-left" and "ellipsis-right" slots)
+     */
     ellipsisText: {
       type: String,
       required: false,
       default: '…',
     },
+    /**
+     * aria-label for the first page item
+     */
     labelFirstPage: {
       type: String,
       required: false,
       default: 'Go to first page',
     },
+    /**
+     * aria-label for the previous page item
+     */
     labelPrevPage: {
       type: String,
       required: false,
       default: 'Go to previous page',
     },
+    /**
+     * aria-label for the next page item
+     */
     labelNextPage: {
       type: String,
       required: false,
       default: 'Go to next page',
     },
+    /**
+     * aria-label for the last page item
+     */
     labelLastPage: {
       type: String,
       required: false,
       default: 'Go to last page',
     },
+    /**
+     * aria-label getter for numbered page items, defaults to "Go to page <page_number>"
+     */
     labelPage: {
       type: Function,
       required: false,
       default: (page) => `Go to page ${page}`,
     },
+    /**
+     * Controls the component\'s horizontal alignment, value should be one of "left", "center", "right" or "fill"
+     */
     align: {
       type: String,
       required: false,
@@ -281,15 +326,28 @@ export default {
     handleClick(event, value) {
       if (!this.isLinkBased) {
         event.preventDefault();
+        /**
+         * Emitted when the page changes
+         * @event input
+         * @arg {number} value The page that just got loaded
+         */
         this.$emit('input', value);
       }
     },
     handlePrevious(event, value) {
       this.handleClick(event, value);
+      /**
+       * Emitted when the "previous" button is clicked
+       * @event previous
+       */
       this.$emit('previous');
     },
     handleNext(event, value) {
       this.handleClick(event, value);
+      /**
+       * Emitted when the "next" button is clicked
+       * @event next
+       */
       this.$emit('next');
     },
   },
@@ -319,6 +377,12 @@ export default {
         :href="isLinkBased ? linkGen(value - 1) : '#'"
         @click="handlePrevious($event, value - 1)"
       >
+        <!-- 
+          @slot Content for the "previous" button. Overrides the "prevText" prop. 
+          @binding {boolean} active
+          @binding {boolean} disabled
+          @binding {number} number
+          -->
         <slot name="previous" v-bind="{ page: value - 1, disabled: prevPageIsDisabled }">
           <gl-icon name="chevron-left" />
           <span>{{ prevText }}</span>
@@ -342,6 +406,21 @@ export default {
         v-bind="item.attrs"
         v-on="item.listeners"
       >
+        <!--
+        Content for page number buttons.
+        @slot page-number
+        @binding {boolean} active
+        @binding {boolean} disabled
+        @binding {number} number
+        -->
+        <!--
+        Content for the left ellipsis. Overrides the "ellipsisText" prop.
+        @slot ellipsis-left
+        -->
+        <!--
+        Content for the right ellipsis. Overrides the "ellipsisText" prop.
+        @slot ellipsis-right
+        -->
         <slot :name="item.slot" v-bind="item.slotData">{{ item.content }}</slot>
       </component>
     </li>
@@ -361,6 +440,12 @@ export default {
         :href="isLinkBased ? linkGen(value + 1) : '#'"
         @click="handleNext($event, value + 1)"
       >
+        <!-- 
+          @slot Content for the "next" button. Overrides the "nextText" prop. 
+          @binding {boolean} active
+          @binding {boolean} disabled
+          @binding {number} number
+          -->
         <slot name="next" v-bind="{ page: value + 1, disabled: nextPageIsDisabled }">
           <span>{{ nextText }}</span>
           <gl-icon name="chevron-right" />