@gitlab/ui 32.46.0 → 32.50.0

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

@@ -1,105 +1,6 @@
-import examples from './examples';
 import * as description from './keyset_pagination.md';
 
 export default {
   description,
   followsDesignSystem: true,
-  bootstrapComponent: false,
-  examples,
-  propsInfo: {
-    hasPreviousPage: {
-      type: Boolean,
-      required: false,
-      default: false,
-      additionalInfo: 'Whether or not the "Prev" button should be enabled',
-    },
-    hasNextPage: {
-      type: Boolean,
-      required: false,
-      default: false,
-      additionalInfo: 'Whether or not the "Next" button should be enabled',
-    },
-    startCursor: {
-      type: String,
-      required: false,
-      default: null,
-      additionalInfo:
-        '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.',
-    },
-    endCursor: {
-      type: String,
-      required: false,
-      default: null,
-      additionalInfo:
-        '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.',
-    },
-
-    prevText: {
-      type: String,
-      required: false,
-      default: 'Prev',
-      additionalInfo:
-        'The text that will be rendered inside the "Prev" button. It\'s important to provide this parameter since the default text is not translatable.',
-    },
-    prevButtonLink: {
-      type: String,
-      required: false,
-      default: null,
-      additionalInfo:
-        '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.',
-    },
-    nextText: {
-      type: String,
-      required: false,
-      default: 'Next',
-      additionalInfo:
-        'The text that will be rendered inside the "Next" button. It\'s important to provide this parameter since the default text is not translatable.',
-    },
-    nextButtonLink: {
-      type: String,
-      required: false,
-      default: null,
-      additionalInfo:
-        '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.',
-    },
-    disabled: {
-      type: Boolean,
-      required: false,
-      default: false,
-      additionalInfo:
-        'Whether or not both buttons should be disabled (regardless of the "hasPreviousPage" and "hasNextPage" values).',
-    },
-  },
-  events: [
-    {
-      event: 'prev',
-      description: 'Emitted when the "Prev" button is clicked',
-      args: [
-        {
-          arg: 'startCursor',
-          description: 'A cursor that points to the first item in the current page.',
-        },
-      ],
-    },
-    {
-      event: 'next',
-      description: 'Emitted when the "Next" button is clicked',
-      args: [
-        {
-          arg: 'endCursor',
-          description: 'A cursor that points to the last item in the current page',
-        },
-      ],
-    },
-  ],
-  slots: [
-    {
-      name: 'previous-button-content',
-      description: 'Used to customize the appearance of the "Prev" button',
-    },
-    {
-      name: 'next-button-content',
-      description: 'Used to customize the appearance of the "Next" button',
-    },
-  ],
 };

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

@@ -1,5 +1,3 @@
-# Keyset Pagination
-
 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

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

@@ -1,65 +1,67 @@
-import { withKnobs, boolean, text } from '@storybook/addon-knobs';
-import { documentedStoriesOf } from '../../../../documentation/documented_stories';
 import readme from './keyset_pagination.md';
 import GlKeysetPagination from './keyset_pagination.vue';
 
-const components = {
-  GlKeysetPagination,
-};
+const generateProps = ({
+  hasPreviousPage = false,
+  hasNextPage = true,
+  startCursor = 'eyJpZCI6IjE3NTg1ODciLCJyZWxlYXNlZF9hdCI6IjIwMjAtMDgtMjAgMTQ6NDc6MDguNTQ1MjE1MDAwIFVUQyJ9',
+  endCursor = 'eyJpZCI6IjEyNjcxNzkiLCJyZWxlYXNlZF9hdCI6IjIwMjAtMDItMTkgMjE6MDA6MDUuODU5NTQ2MDAwIFVUQyJ9',
+  prevText = 'Prev',
+  nextText = 'Next',
+  prevButtonLink = '',
+  nextButtonLink = '',
+  disabled = false,
+} = {}) => ({
+  hasPreviousPage,
+  hasNextPage,
+  startCursor,
+  endCursor,
+  prevText,
+  nextText,
+  prevButtonLink,
+  nextButtonLink,
+  disabled,
+});
 
-function generateProps() {
-  return {
-    hasPreviousPage: {
-      type: Boolean,
-      default: boolean('hasPreviousPage', false),
-    },
-    hasNextPage: {
-      type: Boolean,
-      default: boolean('hasNextPage', true),
-    },
-    startCursor: {
-      type: String,
-      default: text(
-        'startCursor',
-        'eyJpZCI6IjE3NTg1ODciLCJyZWxlYXNlZF9hdCI6IjIwMjAtMDgtMjAgMTQ6NDc6MDguNTQ1MjE1MDAwIFVUQyJ9'
-      ),
-    },
-    endCursor: {
-      type: String,
-      default: text(
-        'endCursor',
-        'eyJpZCI6IjEyNjcxNzkiLCJyZWxlYXNlZF9hdCI6IjIwMjAtMDItMTkgMjE6MDA6MDUuODU5NTQ2MDAwIFVUQyJ9'
-      ),
-    },
-    prevText: {
-      type: String,
-      default: text('prevText'),
-    },
-    nextText: {
-      type: String,
-      default: text('nextText'),
-    },
-    prevButtonLink: {
-      type: String,
-      default: text('prevButtonLink'),
-    },
-    nextButtonLink: {
-      type: String,
-      default: text('nextButtonLink'),
+const Template = (args, { argTypes }) => ({
+  components: { GlKeysetPagination },
+  props: Object.keys(argTypes),
+  template: `
+      <gl-keyset-pagination v-bind="$props"/>
+    `,
+});
+
+/* eslint-disable no-alert */
+export const Events = (args, { argTypes }) => ({
+  components: { GlKeysetPagination },
+  props: Object.keys(argTypes),
+  methods: {
+    onPrev(startCursor) {
+      alert(`"prev" event fired with start cursor: "${startCursor}"`);
     },
-    disabled: {
-      type: Boolean,
-      default: boolean('disabled', false),
+    onNext(endCursor) {
+      alert(`"next" event fired with end cursor: "${endCursor}"`);
     },
-  };
-}
-
-documentedStoriesOf('base/keyset-pagination', readme)
-  .addDecorator(withKnobs)
-  .add('default', () => ({
-    components,
-    props: generateProps(),
-    template: `
-      <gl-keyset-pagination v-bind="$props"/>
+  },
+  template: `
+      <gl-keyset-pagination v-bind="$props" @prev="onPrev($event)" @next="onNext($event)" />
     `,
-  }));
+});
+Events.args = generateProps({ hasPreviousPage: true });
+
+export const Default = Template.bind({});
+Default.args = generateProps();
+
+export default {
+  title: 'base/keyset-pagination',
+  component: GlKeysetPagination,
+  parameters: {
+    bootstrapComponent: false,
+    knobs: { disable: true },
+    docs: {
+      description: {
+        component: readme,
+      },
+    },
+  },
+};

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

@@ -16,47 +16,79 @@ export default {
     // 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 "Prev" button.
+     * It\'s important to provide this parameter since the default text is not translatable.
+     */
     prevText: {
       type: String,
       required: false,
       default: 'Prev',
     },
+    /**
+     * 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 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: '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,
@@ -74,6 +106,7 @@ export default {
       data-testid="prevButton"
       @click="$emit('prev', startCursor)"
     >
+      <!-- @slot Used to customize the appearance of the "Prev" button -->
       <slot name="previous-button-content">
         <div class="gl-display-flex gl-align-center">
           <gl-icon name="chevron-left" />
@@ -87,6 +120,7 @@ export default {
       data-testid="nextButton"
       @click="$emit('next', endCursor)"
     >
+      <!-- @slot Used to customize the appearance of the "Next" button -->
       <slot name="next-button-content">
         <div class="gl-display-flex gl-align-center">
           {{ nextText }}

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

@@ -1,48 +1,6 @@
-import examples from './examples';
 import description from './modal.md';
 
 export default {
-  bootstrapComponent: 'b-modal',
   followsDesignSystem: true,
   description,
-  examples,
-  slots: [
-    {
-      name: 'modal-header',
-      description:
-        'Entire modal header container contents (including the close button on the top right corner)',
-    },
-    {
-      name: 'modal-title',
-      description: 'Modal title. If modal-header slot is used, this slot will not be shown.',
-    },
-    {
-      name: 'modal-header-close',
-      description:
-        'Content of Modal header close button. If modal-header slot is used, this slot will not be shown.',
-    },
-    {
-      name: 'modal-footer',
-      description:
-        'Populated via props: modal-action-primary, modal-action-cancel and modal-action-secondary.',
-    },
-  ],
-  events: [
-    {
-      event: '@primary',
-      description: 'Emitted when clicked on modal-action-primary',
-    },
-    {
-      event: '@secondary',
-      description: 'Emitted when clicked on modal-action-secondary',
-    },
-    {
-      event: '@canceled',
-      description: 'Emitted when clicked on modal-action-cancel',
-    },
-    {
-      event: '@change',
-      description: 'Emitted when the modal visibility changes',
-    },
-  ],
 };

package/src/components/base/modal/modal.md

@@ -1,8 +1,3 @@
-# Modal
-
-<!-- STORY -->
-## Usage
-
 Modals are used to reveal critical information, show information without losing context, or when the
 system requires a user response. Modals can also fragment a complex workflow into simpler steps and
 should serve a single purpose dedicated to completing the user’s task.
@@ -22,7 +17,7 @@ The `modal-footer` slot should only be populated via props: `action-primary`, `a
 `action-cancel`. These props allow you to handle how a primary, secondary and cancel button will
 behave in the modals footer. The props receive an object as such:
 
-~~~js
+```js
 {
   text: 'Save Changes',
   attributes: [
@@ -32,4 +27,4 @@ behave in the modals footer. The props receive an object as such:
     ...
   ]
 }
-~~~
+```

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

@@ -1,19 +1,8 @@
-import { withKnobs, select, number, boolean } from '@storybook/addon-knobs';
-import { documentedStoriesOf } from '../../../../documentation/documented_stories';
 import { GlModal, GlModalDirective, GlButton } from '../../../../index';
 import { variantOptionsWithNoDefault } from '../../../utils/constants';
 import readme from './modal.md';
 
-const components = {
-  GlModal,
-  GlButton,
-};
-
-const directives = {
-  GlModalDirective,
-};
-
-function generateTemplate({ props = {}, slots = {} } = {}) {
+const generateTemplate = ({ props = {}, slots = {} } = {}) => {
   const extraProps = Object.entries(props)
     .map(([key, value]) => `:${key}="${value}"`)
     .join('\n        ');
@@ -51,97 +40,130 @@ function generateTemplate({ props = {}, slots = {} } = {}) {
       </gl-modal>
     </div>
   `;
-}
+};
+
+const Template = (args, { argTypes }) => ({
+  components: { GlModal, GlButton },
+  directives: { GlModalDirective },
+  props: Object.keys(argTypes),
+  template: generateTemplate(),
+});
 
-function generateProps({
+const generateProps = ({
   variant = variantOptionsWithNoDefault.default,
   contentPagraphs = 1,
   scrollable = false,
   visible = false,
-} = {}) {
-  return {
+} = {}) => ({
+  headerBgVariant: variant,
+  headerBorderVariant: variant,
+  headerTextVariant: variant,
+  bodyBgVariant: variant,
+  bodyTextVariant: variant,
+  footerBgVariant: variant,
+  footerBorderVariant: variant,
+  footerTextVariant: variant,
+  contentParagraphs: contentPagraphs,
+  scrollable,
+  visible,
+});
+
+export const Default = Template.bind({});
+Default.args = generateProps();
+
+export const OpenedModal = Template.bind({});
+OpenedModal.args = generateProps({ visible: true });
+
+export const WithScrollingContent = Template.bind({});
+WithScrollingContent.args = generateProps({
+  contentPagraphs: 100,
+  scrollable: true,
+  visible: true,
+});
+
+export const WithAHeader = (args, { argTypes }) => ({
+  components: { GlModal, GlButton },
+  directives: { GlModalDirective },
+  props: Object.keys(argTypes),
+  template: generateTemplate({
+    slots: {
+      'modal-header': '<h4>A custom header</h4>',
+    },
+  }),
+});
+WithAHeader.args = generateProps({ visible: true });
+
+export const WithoutAFooter = (args, { argTypes }) => ({
+  components: { GlModal, GlButton },
+  directives: { GlModalDirective },
+  props: Object.keys(argTypes),
+  template: generateTemplate({
+    props: { 'hide-footer': true },
+  }),
+});
+WithoutAFooter.args = generateProps({ visible: true });
+
+export default {
+  title: 'base/modal',
+  components: { GlModal, GlButton },
+  directives: { GlModalDirective },
+  bootstrapComponent: 'b-modal',
+  parameters: {
+    knobs: { disable: true },
+    docs: {
+      description: {
+        component: readme,
+      },
+    },
+  },
+  argTypes: {
     headerBgVariant: {
-      type: String,
-      default: select('header bg', variantOptionsWithNoDefault, variant),
+      control: {
+        type: 'select',
+        options: variantOptionsWithNoDefault,
+      },
     },
     headerBorderVariant: {
-      type: String,
-      default: select('header border', variantOptionsWithNoDefault, variant),
+      control: {
+        type: 'select',
+        options: variantOptionsWithNoDefault,
+      },
     },
     headerTextVariant: {
-      type: String,
-      default: select('header text', variantOptionsWithNoDefault, variant),
+      control: {
+        type: 'select',
+        options: variantOptionsWithNoDefault,
+      },
     },
     bodyBgVariant: {
-      type: String,
-      default: select('body bg', variantOptionsWithNoDefault, variant),
+      control: {
+        type: 'select',
+        options: variantOptionsWithNoDefault,
+      },
     },
     bodyTextVariant: {
-      type: String,
-      default: select('body text', variantOptionsWithNoDefault, variant),
+      control: {
+        type: 'select',
+        options: variantOptionsWithNoDefault,
+      },
     },
     footerBgVariant: {
-      type: String,
-      default: select('footer bg', variantOptionsWithNoDefault, variant),
+      control: {
+        type: 'select',
+        options: variantOptionsWithNoDefault,
+      },
     },
     footerBorderVariant: {
-      type: String,
-      default: select('footer border', variantOptionsWithNoDefault, variant),
+      control: {
+        type: 'select',
+        options: variantOptionsWithNoDefault,
+      },
     },
     footerTextVariant: {
-      type: String,
-      default: select('footer text', variantOptionsWithNoDefault, variant),
-    },
-    contentParagraphs: {
-      type: Number,
-      default: number('content paragraphs', contentPagraphs),
-    },
-    scrollable: {
-      type: Boolean,
-      default: boolean('scrollable', scrollable),
-    },
-    visible: {
-      type: Boolean,
-      default: visible,
-    },
-  };
-}
-
-documentedStoriesOf('base/modal', readme)
-  .addDecorator(withKnobs)
-  .add('default', () => ({
-    props: generateProps(),
-    components,
-    directives,
-    template: generateTemplate(),
-  }))
-  .add('opened modal', () => ({
-    props: generateProps({ visible: true }),
-    components,
-    directives,
-    template: generateTemplate(),
-  }))
-  .add('with scrolling content', () => ({
-    props: generateProps({ contentPagraphs: 100, scrollable: true, visible: true }),
-    components,
-    directives,
-    template: generateTemplate(),
-  }))
-  .add('with a header', () => ({
-    props: generateProps({ visible: true }),
-    components,
-    directives,
-    template: generateTemplate({
-      slots: {
-        'modal-header': '<h4>A custom header</h4>',
+      control: {
+        type: 'select',
+        options: variantOptionsWithNoDefault,
       },
-    }),
-  }))
-  .add('without a footer', () => ({
-    props: generateProps({ visible: true }),
-    components,
-    directives,
-    template: generateTemplate({
-      props: { 'hide-footer': true },
-    }),
-  }));
+    },
+  },
+};

package/src/components/base/modal/modal.vue

@@ -139,6 +139,10 @@ export default {
 </script>
 
 <template>
+  <!-- 
+  Emitted when the modal visibility changes
+  @event change
+ -->
   <b-modal
     :id="modalId"
     ref="modal"
@@ -156,19 +160,27 @@ export default {
   >
     <slot></slot>
     <template #modal-header>
+      <!-- @slot Entire modal header container contents (including the close button on the top right corner) -->
       <slot name="modal-header">
         <h4 class="modal-title">
+          <!-- @slot Modal title. If modal-header slot is used, this slot will not be shown. -->
           <slot name="modal-title">{{ title }}</slot>
         </h4>
       </slot>
+      <!-- @slot Content of Modal header close button. If modal-header slot is used, this slot will not be shown. -->
       <close-button ref="close-button" :label="dismissLabel" @click="close" />
     </template>
     <!-- eslint-disable-next-line vue/no-deprecated-slot-attribute -->
     <slot slot="modal-ok" name="modal-ok"></slot>
     <!-- eslint-disable-next-line vue/no-deprecated-slot-attribute -->
     <slot slot="modal-cancel" name="modal-cancel"></slot>
+    <!-- @slot Populated via props: modal-action-primary, modal-action-cancel and modal-action-secondary. -->
     <!-- eslint-disable-next-line vue/no-deprecated-slot-attribute -->
     <slot slot="modal-footer" name="modal-footer">
+      <!-- 
+        Emitted when clicked on modal-action-cancel
+        @event canceled
+       -->
       <gl-button
         v-if="actionCancel"
         class="js-modal-action-cancel"
@@ -177,6 +189,10 @@ export default {
       >
         {{ actionCancel.text }}
       </gl-button>
+      <!-- 
+        Emitted when clicked on modal-action-secondary
+        @event secondary
+       -->
       <gl-button
         v-if="actionSecondary"
         class="js-modal-action-secondary"
@@ -185,6 +201,10 @@ export default {
       >
         {{ actionSecondary.text }}
       </gl-button>
+      <!-- 
+        Emitted when clicked on modal-action-primary
+        @event primary
+       -->
       <gl-button
         v-if="actionPrimary"
         class="js-modal-action-primary"