@gitlab/ui 38.0.1 → 38.2.1

package/CHANGELOG.md

@@ -1,3 +1,30 @@
+## [38.2.1](https://gitlab.com/gitlab-org/gitlab-ui/compare/v38.2.0...v38.2.1) (2022-04-01)
+
+
+### Bug Fixes
+
+* **GlFilteredSearch:** Generate stable token keys ([88dccde](https://gitlab.com/gitlab-org/gitlab-ui/commit/88dccde9f4df1352a7e06e831de8baced4a8d18f))
+
+# [38.2.0](https://gitlab.com/gitlab-org/gitlab-ui/compare/v38.1.0...v38.2.0) (2022-03-31)
+
+
+### Bug Fixes
+
+* **GlFilteredSearch:** Stop mutating value prop ([79aa5bc](https://gitlab.com/gitlab-org/gitlab-ui/commit/79aa5bc9712e293e08842c8c0234e29511de3401))
+* **GlFilteredSearch:** Stop mutating value prop ([31808db](https://gitlab.com/gitlab-org/gitlab-ui/commit/31808dbcf6b3c412db7191fe12317009b0d95542))
+
+
+### Features
+
+* **audio:** Implementation of GitLab Flavoured Markdown audio styles ([e4c613f](https://gitlab.com/gitlab-org/gitlab-ui/commit/e4c613f0892b7b1bf3bd97b17e64e4d2e6492ebe))
+
+# [38.1.0](https://gitlab.com/gitlab-org/gitlab-ui/compare/v38.0.1...v38.1.0) (2022-03-28)
+
+
+### Features
+
+* **GlBreadcrumbItem:** implement custom component, add `aria-current="page"` to the last breadcrumb link ([6c246e4](https://gitlab.com/gitlab-org/gitlab-ui/commit/6c246e49d3132be4f0f4d70b0f358af4622a27f6))
+
 ## [38.0.1](https://gitlab.com/gitlab-org/gitlab-ui/compare/v38.0.0...v38.0.1) (2022-03-21)
 
 

package/README.md

@@ -46,7 +46,7 @@ GitLab UI provides component styles, a utility-class library, and SCSS utilities
 
 ## Quick start - development
 
-Make sure you have [Node](https://nodejs.org/en/) 14.x (LTS) and [Yarn](https://yarnpkg.com/) 1.22
+Make sure you have [Node](https://nodejs.org/en/) 16.x (LTS) and [Yarn](https://yarnpkg.com/) 1.22
 or newer.
 
 ```sh

package/dist/components/base/breadcrumb/breadcrumb.js

@@ -1,16 +1,17 @@
-import { BBreadcrumb, BBreadcrumbItem } from 'bootstrap-vue/esm/index.js';
+import { BBreadcrumb } from 'bootstrap-vue/esm/index.js';
 import GlIcon from '../icon/icon';
 import GlButton from '../button/button';
 import { GlTooltipDirective } from '../../../directives/tooltip';
+import GlBreadcrumbItem from './breadcrumb_item';
 import __vue_normalize__ from 'vue-runtime-helpers/dist/normalize-component.js';
 
 const COLLAPSE_AT_SIZE = 4;
 var script = {
   components: {
     BBreadcrumb,
-    BBreadcrumbItem,
     GlIcon,
-    GlButton
+    GlButton,
+    GlBreadcrumbItem
   },
   directives: {
     GlTooltip: GlTooltipDirective
@@ -72,7 +73,7 @@ var script = {
         this.$refs.firstItem[0].querySelector('a').focus();
       } catch (e) {
         /* eslint-disable-next-line no-console */
-        console.error(`Failed to set focus on the last breadcrumb item.`);
+        console.error(`Failed to set focus on the first breadcrumb item.`);
       }
     },
 
@@ -82,6 +83,10 @@ var script = {
 
     isItemCollapsed(index) {
       return this.hasCollapsible && this.isListCollapsed && !this.nonCollapsibleIndices.includes(index);
+    },
+
+    getAriaCurrentAttr(index) {
+      return this.isLastItem(index) ? 'page' : false;
     }
 
   }
@@ -91,7 +96,7 @@ var script = {
 const __vue_script__ = script;
 
 /* template */
-var __vue_render__ = function () {var _vm=this;var _h=_vm.$createElement;var _c=_vm._self._c||_h;return _c('nav',{staticClass:"gl-breadcrumbs",attrs:{"aria-label":"Breadcrumb"}},[_vm._t("avatar"),_vm._v(" "),_c('b-breadcrumb',_vm._g(_vm._b({staticClass:"gl-breadcrumb-list"},'b-breadcrumb',_vm.$attrs,false),_vm.$listeners),[_vm._l((_vm.items),function(item,index){return [_c('b-breadcrumb-item',{key:index,ref:_vm.isFirstItem(index) ? 'firstItem' : null,refInFor:true,staticClass:"gl-breadcrumb-item",class:{ 'gl-display-none': _vm.isItemCollapsed(index) },attrs:{"text":item.text,"href":item.href,"to":item.to}},[_c('span',[_vm._v(_vm._s(item.text))]),_vm._v(" "),(!_vm.isLastItem(index))?_c('span',{key:(index + " " + (item.text)),staticClass:"gl-breadcrumb-separator",attrs:{"data-testid":"separator"}},[_vm._t("separator",[_c('gl-icon',{attrs:{"name":"chevron-right"}})])],2):_vm._e()]),_vm._v(" "),(_vm.showCollapsedBreadcrumbsExpander(index))?[_c('gl-button',{directives:[{name:"gl-tooltip",rawName:"v-gl-tooltip.hover",value:('Show all breadcrumbs'),expression:"'Show all breadcrumbs'",modifiers:{"hover":true}}],attrs:{"aria-label":"Show all breadcrumbs","data-testid":"collapsed-expander","icon":"ellipsis_h","category":"primary"},on:{"click":_vm.expandBreadcrumbs}}),_vm._v(" "),_c('span',{key:"expander",staticClass:"gl-display-inline-flex gl-text-gray-500",attrs:{"data-testid":"expander-separator"}},[_vm._t("separator",[_c('gl-icon',{attrs:{"name":"chevron-right"}})])],2)]:_vm._e()]})],2)],2)};
+var __vue_render__ = function () {var _vm=this;var _h=_vm.$createElement;var _c=_vm._self._c||_h;return _c('nav',{staticClass:"gl-breadcrumbs",attrs:{"aria-label":"Breadcrumb"}},[_vm._t("avatar"),_vm._v(" "),_c('b-breadcrumb',_vm._g(_vm._b({staticClass:"gl-breadcrumb-list"},'b-breadcrumb',_vm.$attrs,false),_vm.$listeners),[_vm._l((_vm.items),function(item,index){return [_c('gl-breadcrumb-item',{key:index,ref:_vm.isFirstItem(index) ? 'firstItem' : null,refInFor:true,class:{ 'gl-display-none': _vm.isItemCollapsed(index) },attrs:{"text":item.text,"href":item.href,"to":item.to,"aria-current":_vm.getAriaCurrentAttr(index)}},[_c('span',[_vm._v(_vm._s(item.text))]),_vm._v(" "),(!_vm.isLastItem(index))?_c('span',{key:(index + " " + (item.text)),staticClass:"gl-breadcrumb-separator",attrs:{"data-testid":"separator"}},[_vm._t("separator",[_c('gl-icon',{attrs:{"name":"chevron-right"}})])],2):_vm._e()]),_vm._v(" "),(_vm.showCollapsedBreadcrumbsExpander(index))?[_c('gl-button',{directives:[{name:"gl-tooltip",rawName:"v-gl-tooltip.hover",value:('Show all breadcrumbs'),expression:"'Show all breadcrumbs'",modifiers:{"hover":true}}],attrs:{"aria-label":"Show all breadcrumbs","data-testid":"collapsed-expander","icon":"ellipsis_h","category":"primary"},on:{"click":_vm.expandBreadcrumbs}}),_vm._v(" "),_c('span',{key:"expander",staticClass:"gl-display-inline-flex gl-text-gray-500",attrs:{"data-testid":"expander-separator"}},[_vm._t("separator",[_c('gl-icon',{attrs:{"name":"chevron-right"}})])],2)]:_vm._e()]})],2)],2)};
 var __vue_staticRenderFns__ = [];
 
   /* style */

package/dist/components/base/{filtered_search/examples/filtered_search.single_unique.example.js → breadcrumb/breadcrumb_item.js}

@@ -1,41 +1,45 @@
+import { BLink } from 'bootstrap-vue/esm/index.js';
 import __vue_normalize__ from 'vue-runtime-helpers/dist/normalize-component.js';
 
-const testTokens = [{
-  type: 'unique',
-  title: 'Unique',
-  icon: 'document',
-  token: 'gl-filtered-search-token',
-  operators: [{
-    value: '=',
-    description: 'is',
-    default: 'true'
-  }],
-  options: [{
-    icon: 'heart',
-    title: 'heart',
-    value: 1
-  }, {
-    icon: 'hook',
-    title: 'hook',
-    value: 2
-  }],
-  unique: true
-}];
 var script = {
-  data() {
-    return {
-      tokens: testTokens,
-      value: []
-    };
-  }
+  components: {
+    BLink
+  },
+  inheritAttrs: false,
+  props: {
+    text: {
+      type: String,
+      required: false,
+      default: null
+    },
+    to: {
+      type: [String, Object],
+      required: false,
+      default: null
+    },
+    href: {
+      type: String,
+      required: false,
+      default: null
+    },
+    ariaCurrent: {
+      type: [String, Boolean],
+      required: false,
+      default: false,
+
+      validator(value) {
+        return [false, 'page'].indexOf(value) !== -1;
+      }
 
+    }
+  }
 };
 
 /* script */
 const __vue_script__ = script;
 
 /* template */
-var __vue_render__ = function () {var _vm=this;var _h=_vm.$createElement;var _c=_vm._self._c||_h;return _c('div',[_vm._v("\n  "+_vm._s(_vm.value)+"\n  "),_c('gl-filtered-search',{attrs:{"available-tokens":_vm.tokens},model:{value:(_vm.value),callback:function ($$v) {_vm.value=$$v;},expression:"value"}})],1)};
+var __vue_render__ = function () {var _vm=this;var _h=_vm.$createElement;var _c=_vm._self._c||_h;return _c('li',{staticClass:"gl-breadcrumb-item"},[_c('b-link',{attrs:{"href":_vm.href,"to":_vm.to,"aria-current":_vm.ariaCurrent}},[_vm._t("default",[_vm._v(_vm._s(_vm.text))])],2)],1)};
 var __vue_staticRenderFns__ = [];
 
   /* style */

package/dist/components/base/dropdown/dropdown.documentation.js

@@ -1,11 +1,7 @@
-import examples from './examples';
-
-var description = "## Usage\n\nThe dropdown component offers a user multiple items or actions to choose from which are initially\ncollapsed behind a button.\n\n### Icon-only dropdown\n\nIcon-only dropdowns must have an accessible name.\nYou can provide this with the combination of `text` and `text-sr-only` props.\n\nOptionally, you can use `no-caret` to remove the caret and `category=\"tertiary\"` to remove the border.\n\n```html\n<gl-dropdown\n  icon=\"ellipsis_v\"\n  text=\"More actions\"\n  :text-sr-only=\"true\"\n  category=\"tertiary\"\n  no-caret\n>\n```\n\n### Button Content\n\nThere are 3 ways to set the dropdown button's content.\n\n1. Use the `text` attribute. This will display the text with the loading spinner (shown with the\n`loading` attribute), icon (if provided by the `icon` attribute), and dropdown caret:\n\n    ```html\n    <gl-dropdown text=\"Button text\">\n    ```\n\n1. Use the `button-text` template. This allows custom content for the button's text, but keeps the\nloading spinner, icon, and dropdown caret:\n\n    ```html\n    <gl-dropdown>\n      <template #button-text>\n        <!-- Loading spinner shown here -->\n        <!-- Icon shown here -->\n        Custom <strong>Content</strong> with <em>HTML</em> via Slot\n        <gl-truncate position=\"middle\" text=\"Truncated button text\"/>\n        <!-- Dropdown arrow shown here -->\n      </template>\n    </gl-dropdown>\n    ```\n\n1. Use the `button-content` template. This will replace everything in the button with the template:\n\n    ```html\n    <gl-dropdown>\n      <template #button-content>\n        Custom <strong>Content</strong> with <em>HTML</em> via Slot\n      </template>\n    </gl-dropdown>\n    ```\n";
+var description = "The dropdown component offers a user multiple items or actions to choose from which are initially\ncollapsed behind a button.\n\n### Icon-only dropdown\n\nIcon-only dropdowns must have an accessible name.\nYou can provide this with the combination of `text` and `text-sr-only` props.\n\nOptionally, you can use `no-caret` to remove the caret and `category=\"tertiary\"` to remove the border.\n\n```html\n<gl-dropdown\n  icon=\"ellipsis_v\"\n  text=\"More actions\"\n  :text-sr-only=\"true\"\n  category=\"tertiary\"\n  no-caret\n>\n```\n\n### Button Content\n\nThere are 3 ways to set the dropdown button's content.\n\n1. Use the `text` attribute. This will display the text with the loading spinner (shown with the\n`loading` attribute), icon (if provided by the `icon` attribute), and dropdown caret:\n\n    ```html\n    <gl-dropdown text=\"Button text\">\n    ```\n\n1. Use the `button-text` template. This allows custom content for the button's text, but keeps the\nloading spinner, icon, and dropdown caret:\n\n    ```html\n    <gl-dropdown>\n      <template #button-text>\n        <!-- Loading spinner shown here -->\n        <!-- Icon shown here -->\n        Custom <strong>Content</strong> with <em>HTML</em> via Slot\n        <gl-truncate position=\"middle\" text=\"Truncated button text\"/>\n        <!-- Dropdown arrow shown here -->\n      </template>\n    </gl-dropdown>\n    ```\n\n1. Use the `button-content` template. This will replace everything in the button with the template:\n\n    ```html\n    <gl-dropdown>\n      <template #button-content>\n        Custom <strong>Content</strong> with <em>HTML</em> via Slot\n      </template>\n    </gl-dropdown>\n    ```\n\n### GlDropdownForm\n\nUnlike `b-dropdown-form`, we do _not_ add any additional padding with the `gl-dropdown-form` component.\nThis is to prevent double padding with `gl-dropdown-item` and similar components, so in most cases\nshouldn't be needed. To add padding, either add a padding utility class to your form, or an inner\nelement with some padding.\n";
 
 var dropdown_documentation = {
   description,
-  bootstrapComponent: 'b-dropdown',
-  examples,
   followsDesignSystem: false
 };
 

package/dist/components/base/dropdown/dropdown_item.documentation.js

@@ -1,8 +1,7 @@
-var description = "# Dropdown Item\n\n<!-- STORY -->\n\n## Usage\n\nThe dropdown item component is meant to be used for clickable entries inside a dropdown component.\nIf you provide the `href` attribute, it renders a link instead of a button.\n";
+var description = "The dropdown item component is meant to be used for clickable entries inside a dropdown component.\nIf you provide the `href` attribute, it renders a link instead of a button.\n";
 
 var dropdown_item_documentation = {
-  description,
-  bootstrapComponent: 'b-dropdown'
+  description
 };
 
 export default dropdown_item_documentation;

package/dist/components/base/filtered_search/filtered_search.documentation.js

@@ -1,6 +1,4 @@
-import examples from './examples';
-
-var filtered_search = "# Filtered Search\n\nThe filtered search component is responsible for managing search with possible filters.\n\n## Usage\n\nEach filter option (named token) requires a separate Vue component. `GlFilteredSearchToken` is an\nexample of such a token.\n\nPrepare array of available token configurations with the following fields:\n\n- `type`: unique identifier of token type\n- `title`: human-readable title of the token\n- `icon`: token icon\n- `token`: (optional) the token Vue component to use (e.g. `AuthorToken`)\n- `dataType`: (optional) identifier of type (for example \"user\") for this filter. Tokens\n  of the same type could be switched without losing their values\n- `unique`: (optional) indicate this token could appear only once in the filter\n- `disabled`: (optional) indicate this token should be hidden from the dropdown\n- `operators`: (optional) an array of selectable operators.\n  Each array item is an object that must contain `value` and `description`, and optionally `default`\n  (e.g. `{ value: '=', description: 'is', default: 'true' }`)\n- `multiSelect`: (optional) when `true`, the suggestions list becomes multi-select instead of single-select.\n  It is discouraged to use this together with `unique`, as `unique` is intended for single-select.\n- `options`: (optional) an array of options which the user can pick after the operator has been selected.\n  The option object can have the following properties defined: `value`, `icon`, `text`, and `default`\n  all of which are expected be of type `string`. If the `default` is omitted, the `value` of the first\n  option will be displayed as a suggestion\n- any additional fields required to configure your component\n\nEach token for filtered search is a Vue component with the following props:\n\n- `value`: an object with a `data` property containing the current value, and optionally an\n`operator` value containing the operator value\n- `active`: indicates if the token is currently active. It's the token's responsibility\n  to render proper control for editing (for example input).\n- `current-value`: current tokens of the filtered search.\n- `index`: current token position in the filtered search.\n- `config`: additional configuration, supplied in filtered search config for this token.\n\nThe token should emit the following events:\n\n- `activate`: when the token requests activation (for example, when being clicked).\n- `deactivate`: when token requests deactivation (for example due to losing blur on input).\n- `destroy`: when token requests self-destruction (for instance for clicking \"X\" sign).\n- `replace`: token requests its replacement with another token.\n- `split`: token requests adding string values after the current token.\n- `complete`: token indicates its editing is completed.\n\n## Examples\n\nDefine a list of available tokens:\n\n```js\nconst availableTokens = [\n  { type: 'static', icon: 'label', title: 'static:token', token: staticToken },\n  { type: 'dynamic', icon: 'rocket', title: 'dynamic:~token', token: dynamicToken },\n];\n```\n\nPass the list of tokens to the search component. Optionally, you can use `v-model` to receive\nrealtime updates:\n\n```js\n <gl-filtered-search :available-tokens=\"tokens\" v-model=\"value\" />\n```\n";
+var filtered_search = "The filtered search component is responsible for managing search with possible filters.\n\n## Usage\n\nEach filter option (named token) requires a separate Vue component. `GlFilteredSearchToken` is an\nexample of such a token.\n\nPrepare array of available token configurations with the following fields:\n\n- `type`: unique identifier of token type\n- `title`: human-readable title of the token\n- `icon`: token icon\n- `token`: (optional) the token Vue component to use (e.g. `AuthorToken`)\n- `dataType`: (optional) identifier of type (for example \"user\") for this filter. Tokens\n  of the same type could be switched without losing their values\n- `unique`: (optional) indicate this token could appear only once in the filter\n- `disabled`: (optional) indicate this token should be hidden from the dropdown\n- `operators`: (optional) an array of selectable operators.\n  Each array item is an object that must contain `value` and `description`, and optionally `default`\n  (e.g. `{ value: '=', description: 'is', default: 'true' }`)\n- `multiSelect`: (optional) when `true`, the suggestions list becomes multi-select instead of single-select.\n  It is discouraged to use this together with `unique`, as `unique` is intended for single-select.\n- `options`: (optional) an array of options which the user can pick after the operator has been selected.\n  The option object can have the following properties defined: `value`, `icon`, `text`, and `default`\n  all of which are expected be of type `string`. If the `default` is omitted, the `value` of the first\n  option will be displayed as a suggestion\n- any additional fields required to configure your component\n\nEach token for filtered search is a Vue component with the following props:\n\n- `value`: an object with a `data` property containing the current value, and optionally an\n`operator` value containing the operator value\n- `active`: indicates if the token is currently active. It's the token's responsibility\n  to render proper control for editing (for example input).\n- `current-value`: current tokens of the filtered search.\n- `index`: current token position in the filtered search.\n- `config`: additional configuration, supplied in filtered search config for this token.\n\nThe token should emit the following events:\n\n- `activate`: when the token requests activation (for example, when being clicked).\n- `deactivate`: when token requests deactivation (for example due to losing blur on input).\n- `destroy`: when token requests self-destruction (for instance for clicking \"X\" sign).\n- `replace`: token requests its replacement with another token.\n- `split`: token requests adding string values after the current token.\n- `complete`: token indicates its editing is completed.\n\n## Examples\n\nDefine a list of available tokens:\n\n```js\nconst availableTokens = [\n  { type: 'static', icon: 'label', title: 'static:token', token: staticToken },\n  { type: 'dynamic', icon: 'rocket', title: 'dynamic:~token', token: dynamicToken },\n];\n```\n\nPass the list of tokens to the search component. Optionally, you can use `v-model` to receive\nrealtime updates:\n\n```html\n\n<gl-filtered-search :available-tokens=\"tokens\" v-model=\"value\" />\n```\n";
 
 var description = /*#__PURE__*/Object.freeze({
   __proto__: null,
@@ -9,69 +7,7 @@ var description = /*#__PURE__*/Object.freeze({
 
 var filtered_search_documentation = {
   description,
-  followsDesignSystem: true,
-  bootstrapComponent: null,
-  examples,
-  propsInfo: {
-    value: {
-      additionalInfo: 'If provided, used as value of filtered search'
-    },
-    historyItems: {
-      additionalInfo: 'If provided, used as history items for this component'
-    },
-    availableTokens: {
-      additionalInfo: 'Available tokens'
-    },
-    placeholder: {
-      additionalInfo: 'If provided, used as history items for this component'
-    },
-    recentSearchesHeader: {
-      additionalInfo: 'i18n for recent searches title within history dropdown'
-    },
-    clearButtonTitle: {
-      additionalInfo: 'i18n for clear button title'
-    },
-    closeButtonTitle: {
-      additionalInfo: 'i18n for close button title within history dropdown'
-    },
-    clearRecentSearchesText: {
-      additionalInfo: 'i18n for recent searches clear text'
-    },
-    suggestionsListClass: {
-      additionalInfo: 'Additional classes to add to the suggestion list menu. NOTE: this not reactive, and the value must be available and fixed when the component is instantiated'
-    },
-    searchButtonAttributes: {
-      additionalInfo: 'HTML attributes to add to the search button'
-    },
-    searchInputAttributes: {
-      additionalInfo: 'HTML attributes to add to the search input'
-    }
-  },
-  events: [{
-    event: 'clear',
-    description: 'Emitted when search is cleared'
-  }, {
-    event: 'submit',
-    args: [{
-      arg: 'tokens',
-      description: '(Array)'
-    }],
-    description: 'Emitted when search is submitted'
-  }, {
-    event: 'history-item-selected',
-    args: [{
-      arg: 'value',
-      description: 'History item'
-    }],
-    description: 'Emitted when item from history is selected'
-  }, {
-    event: 'clear-history',
-    description: 'Emitted when clear history button is clicked'
-  }],
-  slots: [{
-    name: 'history-item',
-    description: 'Slot to customize history item in history dropdown. Used only if using history items'
-  }]
+  followsDesignSystem: true
 };
 
 export default filtered_search_documentation;

package/dist/components/base/filtered_search/filtered_search.js

@@ -5,27 +5,18 @@ import { GlTooltipDirective } from '../../../directives/tooltip';
 import GlIcon from '../icon/icon';
 import GlSearchBoxByClick from '../search_box_by_click/search_box_by_click';
 import GlFilteredSearchTerm from './filtered_search_term';
-import { TERM_TOKEN_TYPE, needDenormalization, denormalizeTokens, isEmptyTerm, INTENT_ACTIVATE_PREVIOUS, normalizeTokens } from './filtered_search_utils';
+import { createTerm, needDenormalization, denormalizeTokens, isEmptyTerm, INTENT_ACTIVATE_PREVIOUS, ensureTokenId, normalizeTokens } from './filtered_search_utils';
 import __vue_normalize__ from 'vue-runtime-helpers/dist/normalize-component.js';
 
 Vue.use(PortalVue);
 let portalUuid = 0;
 
-function createTerm() {
-  let data = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : '';
-  return {
-    type: TERM_TOKEN_TYPE,
-    value: {
-      data
-    }
-  };
-}
-
 function initialState() {
   return [createTerm()];
 }
 
 var script = {
+  name: 'GlFilteredSearch',
   components: {
     GlSearchBoxByClick,
     GlIcon
@@ -49,16 +40,27 @@ var script = {
 
   inheritAttrs: false,
   props: {
+    /**
+     * If provided, used as value of filtered search
+     */
     value: {
       required: false,
       type: Array,
       default: () => []
     },
+
+    /**
+     * Available tokens
+     */
     availableTokens: {
       type: Array,
       required: false,
       default: () => []
     },
+
+    /**
+     * If provided, used as history items for this component
+     */
     placeholder: {
       type: String,
       required: false,
@@ -74,21 +76,38 @@ var script = {
       required: false,
       default: null
     },
+
+    /**
+     * Additional classes to add to the suggestion list menu. NOTE: this not reactive, and the value
+     * must be available and fixed when the component is instantiated
+     */
     suggestionsListClass: {
       type: [String, Array, Object],
       required: false,
       default: null
     },
+
+    /**
+     * Display operators' descriptions instead of their values (e.g., "is" instead of "=").
+     */
     showFriendlyText: {
       type: Boolean,
       required: false,
       default: false
     },
+
+    /**
+     * HTML attributes to add to the search button
+     */
     searchButtonAttributes: {
       type: Object,
       required: false,
       default: () => ({})
     },
+
+    /**
+     * HTML attributes to add to the search input
+     */
     searchInputAttributes: {
       type: Object,
       required: false,
@@ -143,9 +162,22 @@ var script = {
   watch: {
     tokens: {
       handler() {
+        if (process.env.NODE_ENV !== 'production') {
+          const invalidToken = this.tokens.find(token => !token.id);
+
+          if (invalidToken) {
+            throw new Error(`Token does not have an id:\n${JSON.stringify(invalidToken)}`);
+          }
+        }
+
         if (this.tokens.length === 0 || !this.isLastTokenEmpty()) {
           this.tokens.push(createTerm());
         }
+        /**
+         * Emitted when the tokens (value) changes
+         * @property {array} tokens
+         */
+
 
         this.$emit('input', this.tokens);
       },
@@ -244,12 +276,12 @@ var script = {
     },
 
     replaceToken(idx, token) {
-      this.$set(this.tokens, idx, { ...token,
+      this.$set(this.tokens, idx, ensureTokenId({ ...token,
         value: {
           data: '',
           ...token.value
         }
-      });
+      }));
       this.activeTokenIdx = idx;
     },
 
@@ -261,12 +293,7 @@ var script = {
         return;
       }
 
-      const newTokens = newStrings.map(data => ({
-        type: TERM_TOKEN_TYPE,
-        value: {
-          data
-        }
-      }));
+      const newTokens = newStrings.map(data => createTerm(data));
       this.tokens.splice(idx + 1, 0, ...newTokens);
       this.activeTokenIdx = idx + newStrings.length;
     },
@@ -280,6 +307,10 @@ var script = {
     },
 
     submit() {
+      /**
+       * Emitted when search is submitted
+       * @property {array} tokens
+       */
       this.$emit('submit', normalizeTokens(_cloneDeep(this.tokens)));
     },
 
@@ -295,7 +326,7 @@ var script = {
 const __vue_script__ = script;
 
 /* template */
-var __vue_render__ = function () {var _vm=this;var _h=_vm.$createElement;var _c=_vm._self._c||_h;return _c('gl-search-box-by-click',_vm._b({attrs:{"value":_vm.tokens,"history-items":_vm.historyItems,"clearable":_vm.hasValue,"search-button-attributes":_vm.searchButtonAttributes,"data-testid":"filtered-search-input"},on:{"submit":_vm.submit,"input":_vm.applyNewValue,"history-item-selected":function($event){return _vm.$emit('history-item-selected', $event)},"clear":function($event){return _vm.$emit('clear')},"clear-history":function($event){return _vm.$emit('clear-history')}},scopedSlots:_vm._u([{key:"history-item",fn:function(slotScope){return [_vm._t("history-item",null,null,slotScope)]}},{key:"input",fn:function(){return [_c('div',{staticClass:"gl-filtered-search-scrollable"},[_vm._l((_vm.tokens),function(token,idx){return [_c(_vm.getTokenComponent(token.type),{key:((token.type) + "-" + idx),ref:"tokens",refInFor:true,tag:"component",staticClass:"gl-filtered-search-item",class:{
+var __vue_render__ = function () {var _vm=this;var _h=_vm.$createElement;var _c=_vm._self._c||_h;return _c('gl-search-box-by-click',_vm._b({attrs:{"value":_vm.tokens,"history-items":_vm.historyItems,"clearable":_vm.hasValue,"search-button-attributes":_vm.searchButtonAttributes,"data-testid":"filtered-search-input"},on:{"submit":_vm.submit,"input":_vm.applyNewValue,"history-item-selected":function($event){return _vm.$emit('history-item-selected', $event)},"clear":function($event){return _vm.$emit('clear')},"clear-history":function($event){return _vm.$emit('clear-history')}},scopedSlots:_vm._u([{key:"history-item",fn:function(slotScope){return [_vm._t("history-item",null,null,slotScope)]}},{key:"input",fn:function(){return [_c('div',{staticClass:"gl-filtered-search-scrollable"},[_vm._l((_vm.tokens),function(token,idx){return [_c(_vm.getTokenComponent(token.type),{key:token.id,ref:"tokens",refInFor:true,tag:"component",staticClass:"gl-filtered-search-item",class:{
             'gl-filtered-search-last-item': _vm.isLastToken(idx),
           },attrs:{"config":_vm.getTokenEntry(token.type),"active":_vm.activeTokenIdx === idx,"available-tokens":_vm.currentAvailableTokens,"current-value":_vm.tokens,"index":idx,"placeholder":_vm.termPlaceholder,"show-friendly-text":_vm.showFriendlyText,"search-input-attributes":_vm.searchInputAttributes,"is-last-token":_vm.isLastToken(idx)},on:{"activate":function($event){return _vm.activate(idx)},"deactivate":function($event){return _vm.deactivate(token)},"destroy":function($event){return _vm.destroyToken(idx, $event)},"replace":function($event){return _vm.replaceToken(idx, $event)},"complete":_vm.completeToken,"submit":_vm.submit,"split":function($event){return _vm.createTokens(idx, $event)}},model:{value:(token.value),callback:function ($$v) {_vm.$set(token, "value", $$v);},expression:"token.value"}})]})],2),_vm._v(" "),_c('portal-target',{key:_vm.activeTokenIdx,ref:"menu",style:(_vm.suggestionsStyle),attrs:{"name":_vm.portalName,"slim":""}})]},proxy:true}],null,true)},'gl-search-box-by-click',_vm.$attrs,false))};
 var __vue_staticRenderFns__ = [];

package/dist/components/base/filtered_search/filtered_search_suggestion.documentation.js

@@ -1,13 +1,7 @@
-var description = "# Filtered Search Suggestion\n\n<!-- STORY -->\n\n## Usage\n\nThe filtered search suggestion component is a wrapper around `GlDropdownItem`, which registers\nsuggestions in a top-level suggestion list:\n\n```js\n<gl-filtered-search-suggestion-list>\n  <gl-filtered-search-suggestion value=\"foo\">Example suggestion</gl-filtered-search-suggestion>\n  <gl-filtered-search-suggestion value=\"bar\">Example suggestion 2</gl-filtered-search-suggestion>\n</gl-filtered-search-suggestion-list>\n```\n";
+var description = "The filtered search suggestion component is a wrapper around `GlDropdownItem`, which registers\nsuggestions in a top-level suggestion list:\n\n```html\n<gl-filtered-search-suggestion-list>\n  <gl-filtered-search-suggestion value=\"foo\">Example suggestion</gl-filtered-search-suggestion>\n  <gl-filtered-search-suggestion value=\"bar\">Example suggestion 2</gl-filtered-search-suggestion>\n</gl-filtered-search-suggestion-list>\n```\n";
 
 var filtered_search_suggestion_documentation = {
-  description,
-  bootstrapComponent: 'b-dropdown-item',
-  propsInfo: {
-    value: {
-      additionalInfo: 'Value which will be emitted if this suggestion will be selected in list'
-    }
-  }
+  description
 };
 
 export default filtered_search_suggestion_documentation;

package/dist/components/base/filtered_search/filtered_search_suggestion.js

@@ -2,12 +2,16 @@ import GlDropdownItem from '../dropdown/dropdown_item';
 import __vue_normalize__ from 'vue-runtime-helpers/dist/normalize-component.js';
 
 var script = {
+  name: 'GlFilteredSearchSuggestion',
   components: {
     GlDropdownItem
   },
   inject: ['filteredSearchSuggestionListInstance'],
   inheritAttrs: false,
   props: {
+    /**
+     * Value that will be emitted if this suggestion is selected.
+     */
     value: {
       required: true,
       validator: () => true
@@ -55,7 +59,7 @@ var script = {
 const __vue_script__ = script;
 
 /* template */
-var __vue_render__ = function () {var _vm=this;var _h=_vm.$createElement;var _c=_vm._self._c||_h;return _c('gl-dropdown-item',_vm._b({ref:"item",staticClass:"gl-filtered-search-suggestion",class:{ 'gl-filtered-search-suggestion-active': _vm.isActive },attrs:{"href":"#"},nativeOn:{"mousedown":function($event){$event.preventDefault();return _vm.emitValue($event)}}},'gl-dropdown-item',_vm.$attrs,false),[_vm._t("default")],2)};
+var __vue_render__ = function () {var _vm=this;var _h=_vm.$createElement;var _c=_vm._self._c||_h;return _c('gl-dropdown-item',_vm._b({ref:"item",staticClass:"gl-filtered-search-suggestion",class:{ 'gl-filtered-search-suggestion-active': _vm.isActive },attrs:{"data-testid":"filtered-search-suggestion","href":"#"},nativeOn:{"mousedown":function($event){$event.preventDefault();return _vm.emitValue($event)}}},'gl-dropdown-item',_vm.$attrs,false),[_vm._t("default")],2)};
 var __vue_staticRenderFns__ = [];
 
   /* style */

package/dist/components/base/filtered_search/filtered_search_suggestion_list.documentation.js

@@ -1,12 +1,7 @@
-var description = "# Filtered Search Suggestion\n\n<!-- STORY -->\n\n## Usage\n\nThe filtered search suggestion list component is responsible for managing underlying suggestion instances.\nYou obtain the ref for this component and manage suggestion selection via the component public API:\n\n- `getValue()` - Retrieves the current selected suggestion.\n- `nextItem()` - Selects the next suggestion. If last suggestion was selected, selection is cleared.\n- `prevItem()` - Selects the previous suggestion. If first suggestion was selected, selection is cleared.\n\n```js\n<gl-filtered-search-suggestion-list ref=\"suggestions\">\n  <gl-filtered-search-suggestion value=\"foo\">Example suggestion</gl-filtered-search-suggestion>\n  <gl-filtered-search-suggestion value=\"bar\">Example suggestion 2</gl-filtered-search-suggestion>\n</gl-filtered-search-suggestion-list>\n```\n";
+var description = "The filtered search suggestion list component is responsible for managing underlying suggestion instances.\nYou obtain the ref for this component and manage suggestion selection via the component public API:\n\n- `getValue()` - Retrieves the current selected suggestion.\n- `nextItem()` - Selects the next suggestion. If last suggestion was selected, selection is cleared.\n- `prevItem()` - Selects the previous suggestion. If first suggestion was selected, selection is cleared.\n\n```html\n<gl-filtered-search-suggestion-list ref=\"suggestions\">\n  <gl-filtered-search-suggestion value=\"foo\">Example suggestion</gl-filtered-search-suggestion>\n  <gl-filtered-search-suggestion value=\"bar\">Example suggestion 2</gl-filtered-search-suggestion>\n</gl-filtered-search-suggestion-list>\n```\n";
 
 var filtered_search_suggestion_list_documentation = {
-  description,
-  propsInfo: {
-    initialValue: {
-      additionalInfo: 'Value to be initially selected in list'
-    }
-  }
+  description
 };
 
 export default filtered_search_suggestion_list_documentation;

package/dist/components/base/filtered_search/filtered_search_suggestion_list.js

@@ -1,6 +1,7 @@
 import __vue_normalize__ from 'vue-runtime-helpers/dist/normalize-component.js';
 
 var script = {
+  name: 'GlFilteredSearchSuggestionList',
   inject: ['suggestionsListClass'],
 
   provide() {
@@ -10,6 +11,9 @@ var script = {
   },
 
   props: {
+    /**
+     * Value to be initially selected in list.
+     */
     initialValue: {
       required: false,
       validator: () => true,

package/dist/components/base/filtered_search/filtered_search_term.documentation.js

@@ -1,4 +1,4 @@
-var filtered_search_term = "# Filtered Search Term\n\nThe filtered search term is a component for managing \"free input\" in the filtered search component.\nIt is responsible for autocompleting available tokens and \"converting\" to a relevant\ncomponent when an autocomplete item is selected.\n\n## Usage\n\nThis component is internal and is not intended to be used by `@gitlab/ui` users.\n";
+var filtered_search_term = "The filtered search term is a component for managing \"free input\" in the filtered search component.\nIt is responsible for autocompleting available tokens and \"converting\" to a relevant\ncomponent when an autocomplete item is selected.\n\n## Usage\n\nThis component is internal and is not intended to be used by `@gitlab/ui` users.\n";
 
 var description = /*#__PURE__*/Object.freeze({
   __proto__: null,
@@ -6,49 +6,7 @@ var description = /*#__PURE__*/Object.freeze({
 });
 
 var filtered_search_term_documentation = {
-  description,
-  bootstrapComponent: null,
-  propsInfo: {
-    availableTokens: {
-      additionalInfo: 'Tokens available for this filtered search instance'
-    },
-    active: {
-      additionalInfo: 'If this term token is currently active'
-    },
-    value: {
-      additionalInfo: 'Current term value'
-    },
-    searchInputAttributes: {
-      additionalInfo: 'HTML attributes to add to the search input'
-    },
-    isLastToken: {
-      additionalInfo: 'If this is the last token'
-    }
-  },
-  events: [{
-    event: 'activate',
-    description: 'Emitted when this term token is clicked'
-  }, {
-    event: 'deactivate',
-    description: 'Emitted when this term token loses its focus'
-  }, {
-    event: 'destroy',
-    description: 'Emitted when token value is empty and backspace is pressed'
-  }, {
-    event: 'replace',
-    args: [{
-      arg: 'token',
-      description: '(Object) Replacement token configuration'
-    }],
-    description: 'Emitted when autocomplete entry is selected'
-  }, {
-    event: 'split',
-    args: [{
-      arg: 'newTokens',
-      description: '(Array) Token configurations'
-    }],
-    description: 'Emitted when Space is pressed in-between term text'
-  }]
+  description
 };
 
 export default filtered_search_term_documentation;