@gitlab/ui 126.3.0 → 126.3.1

package/src/components/base/avatars_inline/avatars_inline.vue

@@ -12,33 +12,54 @@ export default {
     GlTooltip,
   },
   props: {
+    /**
+     * Array of avatar objects to display
+     */
     avatars: {
       type: Array,
       required: true,
     },
+    /**
+     * Maximum number of avatars to display before collapsing
+     */
     maxVisible: {
       type: Number,
       required: true,
     },
+    /**
+     * Size of each avatar in pixels
+     */
     avatarSize: {
       type: Number,
       required: true,
       validator: (value) => avatarsInlineSizeOptions.includes(value),
     },
+    /**
+     * Whether to show the avatars in collapsed state
+     */
     collapsed: {
       type: Boolean,
       required: false,
       default: false,
     },
+    /**
+     * Screen reader text for the collapsed avatars badge
+     */
     badgeSrOnlyText: {
       type: String,
       required: true,
     },
+    /**
+     * Property name to extract tooltip text from each hidden avatar object
+     */
     badgeTooltipProp: {
       type: String,
       required: false,
       default: '',
     },
+    /**
+     * Maximum number of characters to display in the badge tooltip
+     */
     badgeTooltipMaxChars: {
       type: Number,
       required: false,
@@ -88,6 +109,7 @@ export default {
 <template>
   <div class="gl-avatars-inline" :class="`gl-avatars-inline-${badgeSize}`">
     <div v-for="(avatar, index) in visibleAvatars" :key="index" class="gl-avatars-inline-child">
+      <!-- @slot Custom avatar rendering. Provide avatar object as slot prop. -->
       <slot name="avatar" :avatar="avatar">
         <gl-avatar v-bind="avatar" :size="avatarSize" />
       </slot>

package/src/components/base/badge/badge.vue

@@ -7,6 +7,7 @@ import {
   linkVariantUnstyled,
 } from '../../../utils/constants';
 import GlIcon from '../icon/icon.vue';
+import { logWarning } from '../../../utils/utils';
 
 const variantClass = {
   [badgeVariantOptions.neutral]: 'badge-neutral',
@@ -120,13 +121,6 @@ export default {
     role() {
       return this.hasIconOnly ? 'img' : undefined;
     },
-    ariaLabel() {
-      if (this.$attrs['aria-label']) {
-        return this.$attrs['aria-label'];
-      }
-
-      return this.role === 'img' ? this.icon : undefined;
-    },
     iconSizeComputed() {
       return badgeIconSizeOptions[this.iconSize];
     },
@@ -152,6 +146,14 @@ export default {
       ];
     },
   },
+  mounted() {
+    if (this.hasIconOnly && !this.$attrs['aria-label']) {
+      logWarning(
+        '[GlBadge] Icon-only badges require an aria-label for accessibility. The label should describe the metadata (e.g., "Due date", "Open issue"), not the icon name. See https://design.gitlab.com/components/badge#using-icon-only-badges',
+        this.$el,
+      );
+    }
+  },
 };
 </script>
 
@@ -161,7 +163,6 @@ export default {
     v-bind="computedProps"
     :class="classes"
     :role="role"
-    :aria-label="ariaLabel"
     v-on="$listeners"
   >
     <gl-icon

package/src/components/base/drawer/drawer.vue

@@ -10,25 +10,40 @@ export default {
     GlButton,
   },
   props: {
+    /**
+     * Controls the visibility state of the drawer.
+     */
     open: {
       type: Boolean,
       required: true,
     },
+    /**
+     * Height of the header element (e.g., '64px'). Used to position the drawer below a fixed header.
+     */
     headerHeight: {
       type: String,
       required: false,
       default: '',
     },
+    /**
+     * When true, makes the drawer header sticky so it remains visible when scrolling the drawer content.
+     */
     headerSticky: {
       type: Boolean,
       required: false,
       default: false,
     },
+    /**
+     * Z-index value for the drawer. Useful for controlling stacking order with other elements.
+     */
     zIndex: {
       type: Number,
       required: false,
       default: maxZIndex,
     },
+    /**
+     * Visual variant of the drawer.
+     */
     variant: {
       type: String,
       required: false,
@@ -93,6 +108,10 @@ export default {
       const ESC = 27;
 
       if (this.open && e.keyCode === ESC) {
+        /**
+         * Emits when drawer gets closed (by pressing ESC or clicking the close button).
+         * @event close
+         */
         this.$emit('close');
       }
     },
@@ -108,6 +127,7 @@ export default {
         :class="{ 'gl-drawer-header-sticky': headerSticky }"
       >
         <div class="gl-drawer-title">
+          <!-- @slot Content for the drawer title area in the header. -->
           <slot name="title"></slot>
           <gl-button
             category="tertiary"
@@ -118,6 +138,7 @@ export default {
             @click="$emit('close')"
           />
         </div>
+        <!-- @slot Additional content below the title in the header section. -->
         <slot name="header"></slot>
       </div>
       <div
@@ -127,6 +148,7 @@ export default {
           'gl-drawer-body-scrim': !shouldRenderFooter,
         }"
       >
+        <!-- @slot Main content of the drawer body. -->
         <slot></slot>
       </div>
       <div
@@ -134,6 +156,7 @@ export default {
         class="gl-drawer-footer gl-drawer-footer-sticky gl-drawer-body-scrim-on-footer"
         :style="{ zIndex }"
       >
+        <!-- @slot Content for the sticky footer at the bottom of the drawer. -->
         <slot name="footer"></slot>
       </div>
     </aside>

package/src/components/base/dropdown/dropdown_item.vue

@@ -15,51 +15,81 @@ export default {
   },
   inheritAttrs: false,
   props: {
+    /**
+     * URL for the avatar image to display
+     */
     avatarUrl: {
       type: String,
       required: false,
       default: '',
     },
+    /**
+     * Color variant for the icon on the left side
+     */
     iconColor: {
       type: String,
       required: false,
       default: '',
     },
+    /**
+     * Name of the icon to display on the left side
+     */
     iconName: {
       type: String,
       required: false,
       default: '',
     },
+    /**
+     * Aria label for the right icon button
+     */
     iconRightAriaLabel: {
       type: String,
       required: false,
       default: '',
     },
+    /**
+     * Name of the icon to display on the right side
+     */
     iconRightName: {
       type: String,
       required: false,
       default: '',
     },
+    /**
+     * Whether the dropdown item is checked
+     */
     isChecked: {
       type: Boolean,
       required: false,
       default: false,
     },
+    /**
+     * Whether to show a check icon for this item
+     */
     isCheckItem: {
       type: Boolean,
       required: false,
       default: false,
     },
+    /**
+     * Whether to center the check icon vertically
+     */
     isCheckCentered: {
       type: Boolean,
       required: false,
       default: false,
     },
+    /**
+     * Secondary text to display below the main content
+     */
     secondaryText: {
       type: String,
       required: false,
       default: '',
     },
+    /**
+     * ARIA role for the dropdown item
+     */
     role: {
       type: String,
       required: false,
@@ -93,6 +123,10 @@ export default {
   },
   methods: {
     handleClickIconRight() {
+      /**
+       * Emitted when right icon is clicked.
+       * @event handleClickIconRight
+       */
       this.$emit('click-icon-right');
     },
   },
@@ -115,6 +149,7 @@ export default {
     <gl-icon v-if="iconName" :name="iconName" :class="['gl-dropdown-item-icon', iconColorCss]" />
     <gl-avatar v-if="avatarUrl" :size="32" :src="avatarUrl" />
     <div class="gl-dropdown-item-text-wrapper">
+      <!-- @slot Main content of the dropdown item. -->
       <p class="gl-dropdown-item-text-primary"><slot></slot></p>
       <p v-if="secondaryText" class="gl-dropdown-item-text-secondary">{{ secondaryText }}</p>
     </div>

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

@@ -31,11 +31,17 @@ export default {
       default: () => [{ value: '', name: '' }],
       validator: (options) => options.every((opt) => Object.keys(opt).includes('name', 'value')),
     },
+    /**
+     * Accessible label for the input field. Used for the aria-label attribute.
+     */
     label: {
       type: String,
       required: false,
       default: undefined,
     },
+    /**
+     * Additional CSS class(es) to apply to the input element.
+     */
     inputClass: {
       type: [String, Array, Object],
       required: false,

package/src/components/base/label/label.vue

@@ -16,41 +16,65 @@ export default {
     GlTooltip,
   },
   props: {
+    /**
+     * Background color of the label in hex, rgb, or rgba format
+     */
     backgroundColor: {
       type: String,
       required: true,
       validator: (value) => /^(#|rgb|rgba)/.test(value),
     },
+    /**
+     * Title text of the label
+     */
     title: {
       type: String,
       required: true,
       default: '',
     },
+    /**
+     * Description text shown in tooltip
+     */
     description: {
       type: String,
       required: false,
       default: '',
     },
+    /**
+     * Placement of the tooltip
+     */
     tooltipPlacement: {
       type: String,
       required: false,
       default: 'top',
     },
+    /**
+     * Target URL for the label link
+     */
     target: {
       type: String,
       required: false,
       default: '',
     },
+    /**
+     * Whether the label is scoped (uses :: separator)
+     */
     scoped: {
       type: Boolean,
       required: false,
       default: false,
     },
+    /**
+     * Whether to show the close button
+     */
     showCloseButton: {
       type: Boolean,
       required: false,
       default: false,
     },
+    /**
+     * Whether the label is disabled
+     */
     disabled: {
       type: Boolean,
       required: false,
@@ -98,19 +122,15 @@ export default {
   methods: {
     onClick(e) {
       /**
-       * Emitted when label is clicked
-       *
+       * Emitted when the label is clicked.
        * @event click
-       * @type {object}
        */
       this.$emit('click', e);
     },
     onClose(e) {
       /**
-       * Emitted when x is clicked
-       *
+       * Emitted when the close button is clicked.
        * @event close
-       * @type {object}
        */
       this.$emit('close', e);
     },

package/src/components/base/popover/popover.vue

@@ -16,6 +16,9 @@ export default {
   mixins: [tooltipMixin(popoverRefName)],
   inheritAttrs: false,
   props: {
+    /**
+     * Additional CSS class(es) to apply to the popover.
+     */
     cssClasses: {
       type: [Array, String, Object],
       required: false,
@@ -31,21 +34,33 @@ export default {
       required: false,
       default: 'hover focus',
     },
+    /**
+     * Title text to display in the popover header.
+     */
     title: {
       type: String,
       required: false,
       default: '',
     },
+    /**
+     * When true, displays a close button in the popover header.
+     */
     showCloseButton: {
       type: Boolean,
       required: false,
       default: false,
     },
+    /**
+     * Placement of the popover relative to the target element.
+     */
     placement: {
       type: String,
       required: false,
       default: popoverPlacements.top,
     },
+    /**
+     * Padding (in pixels) between the popover and the viewport boundary.
+     */
     boundaryPadding: {
       type: [Number, String],
       required: false,
@@ -113,6 +128,7 @@ export default {
     v-on="$listeners"
   >
     <template v-if="shouldShowTitle" #title>
+      <!-- @slot Custom content for the popover title -->
       <slot name="title">
         {{ title }}
       </slot>
@@ -124,6 +140,9 @@ export default {
         />
       </div>
     </template>
-    <template v-if="$scopedSlots.default" #default><slot></slot></template>
+    <template v-if="$scopedSlots.default" #default>
+      <!-- @slot Main content of the popover body-->
+      <slot></slot>
+    </template>
   </b-popover>
 </template>

package/src/components/base/progress_bar/progress_bar.vue

@@ -13,27 +13,42 @@ const backgroundClasses = {
 export default {
   name: 'GlProgressBar',
   props: {
+    /**
+     * Accessible label for the progress bar. Used for the aria-label attribute.
+     */
     ariaLabel: {
       type: String,
       required: false,
       default: translate('GlProgressBar.ariaLabel', 'Progress bar'),
     },
+    /**
+     * Current progress value. Should be between 0 and the max value.
+     */
     value: {
       type: [Number, String],
       required: false,
       default: 0,
     },
+    /**
+     * Visual variant of the progress bar.
+     */
     variant: {
       type: String,
       required: false,
       default: 'primary',
       validator: (value) => Object.keys(progressBarVariantOptions).includes(value),
     },
+    /**
+     * Maximum value for the progress bar. The value prop is calculated as a percentage of this.
+     */
     max: {
       type: [Number, String],
       required: false,
       default: 100,
     },
+    /**
+     * Custom height for the progress bar (e.g., '8px', '1rem').
+     */
     height: {
       type: String,
       required: false,

package/src/components/base/search_box_by_type/search_box_by_type.vue

@@ -27,11 +27,17 @@ export default {
       required: false,
       default: '',
     },
+    /**
+     * Whether to render the search box without borders
+     */
     borderless: {
       type: Boolean,
       required: false,
       default: false,
     },
+    /**
+     * Title text for the clear button
+     */
     clearButtonTitle: {
       type: String,
       required: false,
@@ -104,6 +110,10 @@ export default {
       this.$refs.input.$el.focus();
     },
     onInput(value) {
+      /**
+       * Emitted when the input value changes or gets cleared.
+       * @event input
+       */
       this.$emit('input', value);
     },
     onFocusout(event) {
@@ -113,6 +123,10 @@ export default {
         return;
       }
 
+      /**
+       * Emitted when focus leaves the search box (input and clear button).
+       * @event focusout
+       */
       this.$emit('focusout', event);
     },
     onFocusin(event) {
@@ -122,6 +136,10 @@ export default {
         return;
       }
 
+      /**
+       * Emitted when focus enters the search box (input or clear button).
+       * @event focusin
+       */
       this.$emit('focusin', event);
     },
   },

package/src/components/base/tabs/tab/tab.vue

@@ -2,6 +2,7 @@
 <script>
 import isPlainObject from 'lodash/isPlainObject';
 import { BTab } from '../../../../vendor/bootstrap-vue/src/components/tabs/tab';
+import GlBadge from '../../badge/badge.vue';
 
 import { DEFAULT_TAB_TITLE_LINK_CLASS } from '../constants';
 
@@ -9,6 +10,7 @@ export default {
   name: 'GlTab',
   components: {
     BTab,
+    GlBadge,
   },
   inheritAttrs: false,
   props: {
@@ -25,6 +27,24 @@ export default {
       required: false,
       default: null,
     },
+    /**
+     * Display a count badge next to the tab title.
+     */
+    tabCount: {
+      type: Number,
+      required: false,
+      default: null,
+    },
+    /**
+     * Screen reader text to provide context for the tab count value.
+     * Should be the result of calling n__() with the count.
+     * Example: :tab-count-sr-text="n__('%d changed file', '%d changed files', count)"
+     */
+    tabCountSrText: {
+      type: String,
+      required: false,
+      default: null,
+    },
   },
   computed: {
     linkClass() {
@@ -38,19 +58,43 @@ export default {
       }
       return `${titleLinkClass} ${DEFAULT_TAB_TITLE_LINK_CLASS}`.trim();
     },
+    hasTabCount() {
+      return this.tabCount != null && this.tabCount >= 0;
+    },
+  },
+  created() {
+    if (process.env.NODE_ENV !== 'production' && this.hasTabCount && !this.tabCountSrText) {
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[GlTab] When using "tab-count", you should also provide "tab-count-sr-text" for screen reader accessibility. Example: :tab-count-sr-text="n__(\'%d item\', \'%d items\', count)"',
+      );
+    }
   },
 };
 </script>
 
 <template>
   <b-tab
+    :title="hasTabCount ? null : $attrs.title"
     :title-link-class="linkClass"
     :query-param-value="queryParamValue"
     v-bind="$attrs"
     v-on="$listeners"
   >
-    <!-- eslint-disable-next-line @gitlab/vue-prefer-dollar-scopedslots -->
-    <template v-for="slot in Object.keys($slots)" #[slot]>
+    <template v-if="hasTabCount" #title>
+      <slot name="title">{{ $attrs.title }}</slot>
+      <gl-badge
+        class="gl-ml-2"
+        variant="neutral"
+        aria-hidden="true"
+        data-testid="tab-counter-badge"
+      >
+        {{ tabCount }}
+      </gl-badge>
+      <span v-if="tabCountSrText" class="gl-sr-only">{{ tabCountSrText }}</span>
+    </template>
+
+    <template v-for="slot in Object.keys($scopedSlots)" #[slot]>
       <slot :name="slot"></slot>
     </template>
   </b-tab>

package/src/components/base/token/token.vue

@@ -10,6 +10,9 @@ export default {
     CloseButton,
   },
   props: {
+    /**
+     * When true, hides the close button and makes the token non-removable.
+     */
     viewOnly: {
       type: Boolean,
       required: false,
@@ -60,6 +63,7 @@ export default {
 <template>
   <span :class="['gl-token', variantClass, viewOnlyClass]" v-on="$listeners">
     <span class="gl-token-content">
+      <!-- @slot Content to display inside the token -->
       <slot></slot>
       <close-button v-if="!viewOnly" class="gl-token-close" :label="removeLabel" @click="close" />
     </span>

package/src/components/dashboards/dashboard_layout/dashboard_layout.vue

@@ -35,6 +35,33 @@ export default {
       required: false,
       default: true,
     },
+    /**
+     * Adjusts the cell height of the grid. Setting this too high can leave unwanted whitespace
+     * between grid panels. Reduce the number to allow for a more compact grid.
+     * For more information, see:
+     * https://gitlab.com/gitlab-org/gitlab-services/design.gitlab.com/-/issues/3051
+     */
+    cellHeight: {
+      type: Number,
+      required: false,
+
+      /* Magic number:
+       * After allowing for padding, and the panel title row, this leaves us with minimum 48px height for the cell content.
+       * This means text/content with our spacing scale can fit up to 49px without scrolling.
+       */
+      default: 137,
+      validator: (value) => value > 0,
+    },
+    /**
+     * Sets a default minimum height for grid panels. This can still be overriden on a per-panel
+     * basis by setting `value.panels[].gridAttributes.minHeight`
+     */
+    minCellHeight: {
+      type: Number,
+      required: false,
+      default: 1,
+      validator: (value) => value > 0,
+    },
   },
   computed: {
     dashboardHasPanels() {
@@ -104,6 +131,8 @@ export default {
           v-if="dashboardHasPanels"
           :value="config"
           :is-static-grid="isStaticGrid"
+          :cell-height="cellHeight"
+          :min-cell-height="minCellHeight"
           class="-gl-mx-3"
           @input="emitChanges"
         >