@gitlab/ui 115.8.0 → 115.9.1

package/src/components/base/filtered_search/filtered_search.md

@@ -1,76 +0,0 @@
-The filtered search component is responsible for managing search with possible filters.
-
-## Usage
-
-Each filter option (named token) requires a separate Vue component. `GlFilteredSearchToken` is an
-example of such a token.
-
-Prepare array of available token configurations with the following fields:
-
-- `type`: unique identifier of token type
-- `title`: human-readable title of the token
-- `icon`: token icon
-- `token`: (optional) the token Vue component to use (e.g. `AuthorToken`)
-- `dataType`: (optional) identifier of type (for example "user") for this filter. Tokens
-  of the same type could be switched without losing their values
-- `unique`: (optional) indicate this token could appear only once in the filter
-- `disabled`: (optional) indicate this token should be hidden from the dropdown
-- `operators`: (optional) an array of selectable operators.
-  Each array item is an object that must contain `value` and `description`, and optionally `default`
-  (e.g. `{ value: '=', description: 'is', default: 'true' }`)
-- `multiSelect`: (optional) when `true`, the suggestions list becomes multi-select instead of single-select.
-  It is discouraged to use this together with `unique`, as `unique` is intended for single-select.
-- `options`: (optional) an array of options which the user can pick after the
-  operator has been selected. The option object can have the following
-  properties defined: `value: string`, `icon: string`, `title: string`,
-  `component: Object` and `default: boolean`. If `component` is provided, it is
-  is used to render the option in the suggestions list.
-- `optionComponent`: (optional) A component used to render the token option
-  itself when adding a new token or replacing an existing one
-- any additional fields required to configure your component
-
-Each token for filtered search is a Vue component with the following props:
-
-- `value`: an object with a `data` property containing the current value, and optionally an
-  `operator` value containing the operator value
-- `active`: indicates if the token is currently active. It's the token's responsibility
-  to render proper control for editing (for example input).
-- `current-value`: current tokens of the filtered search.
-- `index`: current token position in the filtered search.
-- `config`: additional configuration, supplied in filtered search config for this token.
-
-The token should emit the following events:
-
-- `activate`: when the token requests activation (for example, when being clicked).
-- `deactivate`: when token requests deactivation (for example due to losing blur on input).
-- `destroy`: when token requests self-destruction (for instance for clicking "X" sign).
-- `replace`: token requests its replacement with another token.
-- `split`: token requests adding string values after the current token.
-- `complete`: token indicates its editing is completed.
-
-### Improve space handling
-
-Set the `terms-as-tokens` prop to `true` to enable new term rendering and
-interaction behavior. This makes it easier to input/edit free text tokens, and
-removes the need for quoting values with spaces and other workarounds.
-
-In future, this prop will be enabled by default and eventually removed. Opt in
-to this earlier rather than later to ease migration.
-
-## Examples
-
-Define a list of available tokens:
-
-```js
-const availableTokens = [
-  { type: 'static', icon: 'label', title: 'static:token', token: staticToken },
-  { type: 'dynamic', icon: 'rocket', title: 'dynamic:~token', token: dynamicToken },
-];
-```
-
-Pass the list of tokens to the search component. Optionally, you can use `v-model` to receive
-realtime updates:
-
-```html
-<gl-filtered-search :available-tokens="tokens" v-model="value" terms-as-tokens />
-```

package/src/components/base/filtered_search/filtered_search_suggestion.md

@@ -1,15 +0,0 @@
-The filtered search suggestion component is a wrapper around `GlDropdownItem`, which registers
-suggestions in a top-level suggestion list:
-
-```html
-<gl-filtered-search-suggestion-list>
-  <gl-filtered-search-suggestion value="foo" key="foo-0">Example suggestion</gl-filtered-search-suggestion>
-  <gl-filtered-search-suggestion value="bar" key="bar-1">Example suggestion 2</gl-filtered-search-suggestion>
-</gl-filtered-search-suggestion-list>
-```
-
-> NOTE: Provide a `key` to suggestions of the form `${value}-${index}` (or
-> similar). While using the index in keys is usually frowned upon for
-> performance reasons, the current implementation relies on all suggestions
-> getting destroyed and recreated to keep rendering order in sync with
-> <kbd>Up</kbd>/<kbd>Down</kbd> keyboard interaction.

package/src/components/base/filtered_search/filtered_search_suggestion_list.md

@@ -1,13 +0,0 @@
-The filtered search suggestion list component is responsible for managing underlying suggestion instances.
-You obtain the ref for this component and manage suggestion selection via the component public API:
-
-- `getValue()` - Retrieves the current selected suggestion.
-- `nextItem()` - Selects the next suggestion. If last suggestion was selected, selection is cleared.
-- `prevItem()` - Selects the previous suggestion. If first suggestion was selected, selection is cleared.
-
-```html
-<gl-filtered-search-suggestion-list ref="suggestions">
-  <gl-filtered-search-suggestion value="foo">Example suggestion</gl-filtered-search-suggestion>
-  <gl-filtered-search-suggestion value="bar">Example suggestion 2</gl-filtered-search-suggestion>
-</gl-filtered-search-suggestion-list>
-```

package/src/components/base/filtered_search/filtered_search_term.md

@@ -1,7 +0,0 @@
-The filtered search term is a component for managing "free input" in the filtered search component.
-It is responsible for autocompleting available tokens and "converting" to a relevant
-component when an autocomplete item is selected.
-
-## Usage
-
-This component is internal and is not intended to be used by `@gitlab/ui` users.

package/src/components/base/filtered_search/filtered_search_token.md

@@ -1,23 +0,0 @@
-Filtered search token is a helper component, intended to
-simplify the creation of filters tokens which consist of a title, operators
-and an editable value with autocomplete. This component abstracts token management
-logic and allows you to focus on implementing autocomplete or view logic.
-
-This component is not intended to be used outside of the `GlFilteredSearch` component.
-
-## Usage
-
-Make sure to pass `$listeners` to `gl-filtered-search-token`, or route events properly:
-
-```html
-<gl-filtered-search-token title="Confidential" :active="active" :value="value" v-on="$listeners">
-  <template #suggestions>
-    <gl-filtered-search-suggestion value="Yes"
-      ><gl-icon name="eye-slash" :size="16" /> Yes</gl-filtered-search-suggestion
-    >
-    <gl-filtered-search-suggestion value="No"
-      ><gl-icon name="eye" :size="16" /> No</gl-filtered-search-suggestion
-    >
-  </template>
-</gl-filtered-search-token>
-```

package/src/components/base/filtered_search/filtered_search_token_segment.md

@@ -1,14 +0,0 @@
-The filtered search token segment is a component for managing token input either via free typing
-or by selecting item through dropdown list
-
-## Usage
-
-This component is internal and is not intended to be used by `@gitlab/ui` users.
-
-## Internet Explorer 11
-
-This component uses [`String.prototype.startsWith()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/startsWith)
-and [`String.prototype.endsWith()`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/endsWith)
-under the hood. Make sure those methods are polyfilled if you plan on using the component on IE11.
-
-> NOTE: These methods are already polyfilled in GitLab: [`app/assets/javascripts/commons/polyfills.js#L15-16`](https://gitlab.com/gitlab-org/gitlab/blob/dc60dee6ed6234dda9f032195577cd8fad9646d8/app/assets/javascripts/commons/polyfills.js#L15-16)

package/src/components/base/form/form_checkbox/form_checkbox.md

@@ -1,6 +0,0 @@
-Form checkbox groups for general use inside forms.
-
-## Stacked
-
-By default, the GitLab Design guide mandates the `<gl-form-checkbox-group>` be `stacked` and is
-non-changeable at this time.

package/src/components/base/form/form_input/form_input.md

@@ -1,306 +0,0 @@
-General user input to be used in forms. Create various type inputs such as:
-`text`, `password`, `number`, `url`, `email`, `search`, `range`, `date`
-and more.
-
-```html
-<template>
-  <gl-form-input v-model="text" placeholder="Enter your name"></gl-form-input>
-</template>
-
-<script>
-  export default {
-    data() {
-      return {
-        text: ''
-      }
-    }
-  }
-</script>
-```
-
-## Input type
-
-`<gl-form-input>` defaults to a `text` input, but you can set the `type` prop
-to one of the supported native browser HTML5 types: `text`, `password`,
-`email`, `number`, `url`, `tel`, `search`, `date`, `datetime`
-`datetime-local`, `month`, `week`, `time`, `range`, or `color`.
-
-If the `type` prop is set to an input type that is not supported (see above),
-a `text` input will be rendered.
-
-**Caveats with input types:**
-
-- Not all browsers support all input types, nor do some types render in the same format across
-browser types/versions. Refer to [Can I use](https://caniuse.com/?search=input).
-- Browsers that do not support a particular type will fall back to a `text` input type
-(even though the rendered `type` attribute markup shows the requested type).
-- No testing is performed to see if the requested input type is supported by the browser.
-- Chrome lost support for `datetime` in version 26, Opera in version 15, and Safari in iOS 7.
-Instead of using `datetime`, since support should be deprecated, use `date` and
-`time` as two separate inputs.
-- `date` and `time` inputs are native browser types, and are not a custom date/time picker.
-- For date and time style inputs, where supported, the displayed value in the GUI may be
-different than what is returned by its value (i.e. ordering of year-month-date).
-- Regardless of input type, the value is **always** returned as a string representation.
-- `v-model.lazy` is not supported by `<b-form-input>` (nor any custom Vue component).
-Use the `lazy` prop instead.
-- `v-model` modifiers `.number` and `.trim` can cause unexpected cursor jumps when
-the user is typing (this is a Vue issue with `v-model` on custom components).
-_Avoid using these modifiers_. Use the `number` or `trim` props instead.
-- Older version of Firefox may not support `readonly` for `range` type inputs.
-- Input types that do not support `min`, `max` and `step` (i.e. `text`, `password`,
-`tel`, `email`, `url`, etc.) will silently ignore these values
-(although they will still be rendered on the input markup) if values are provided.
-
-**Caveats with predictive text entry and IME composition entry:**
-
-- When using predictive text auto-suggested words, the `v-model` will no update until
-the auto-suggested word is selected (or a space is typed). If an auto suggested word
-is not selected, the v-model will update with the current _displayed text_ of the input
-when the input is blurred.
-- When using IME composition (ie. Chinese, Japanese, etc.), the `v-model` will not update
-until the IME composition is completed.
-
-### Range type input
-
-Inputs with type `range` render using Bootstrap v4's `.custom-range` class. The track
-(the background) and thumb (the value) are both styled to appear the same across browsers.
-
-Range inputs have implicit values for `min` and `max` of `0` and `100` respectively.
-You may specify new values for those using the `min` and `max` props.
-
-By default, range inputs "snap" to integer values. To change this, you can specify a `step` value.
-In the example below, we double the number of steps by using step="0.5".
-
-```html
-<template>
-  <gl-form-input id="range-2" v-model="value" type="range" min="0" max="5" step="0.5"></gl-form-input>
-</template>
-
-<script>
-  export default {
-    data() {
-      return {
-        value: '2'
-      }
-    }
-  }
-</script>
-```
-
-**Note:** Range inputs (as do all input types) return their value as a string.
-You may need to convert the value to a native number by using `Number(value)`,
-`parseInt(value, 10)`, `parseFloat(value)`, or use the `number` prop.
-
-## Contextual states
-
-Generally speaking, you'll want to use a particular state for specific types of feedback:
-
-- `false` (denotes invalid state) is great for when there's a blocking or required field.
-A user must fill in this field properly to submit the form.
-- `true` (denotes valid state) is ideal for situations when you have per-field validation
-throughout a form and want to encourage a user through the rest of the fields.
-- `null` Displays no validation state (neither valid nor invalid)
-
-To apply one of the contextual state icons on `<gl-form-input>`, set the `state` prop to
-`false` (for invalid), `true` (for valid), or `null` (no validation state).
-
-> **Tip:** Use the [`<gl-form-group>`](?path=/docs/base-form-form-group--docs) component to
-> automatically generate markup for an input with label, validation message, and help text block.
-
-### ARIA `aria-invalid` attribute
-
-Specifically for assistive technologies, invalid form controls can also be assigned
-an `aria-invalid="true"` attribute.
-
-When `<gl-form-input>` has an invalid contextual state (i.e. state is `false`) you
-may also want to set the `<gl-form-input>` prop `aria-invalid` to `true`, or to
-one of the supported values:
-
-- `false`: Convey no errors detected (default)
-- `true` (or `'true'`): Convey that the value has failed validation.
-- `'grammar'` Convey that a grammatical error has been detected.
-- `'spelling'` Convey that a spelling error has been detected.
-
-If `aria-invalid` is not explicitly set and `state` is set to `false`, then the `aria-invalid`
-attribute on the input will automatically be set to `'true'`;
-
-## Formatter support
-
-`<gl-form-input>` optionally supports formatting by passing a function reference to
-the `formatter` prop.
-
-Formatting (when a formatter function is supplied) occurs when the control's native
-`input` and `change` events fire. You can use the boolean prop `lazy-formatter` to
-restrict the formatter function to being called on the control's native `blur` event.
-
-The `formatter` function receives two arguments: the raw `value` of the input element,
-and the native `event` object that triggered the format (if available).
-
-The `formatter` function should return the formatted value as a _string_.
-
-Formatting does not occur if a `formatter` is not provided.
-
-```html
-<template>
-  <div>
-    <gl-form-group
-      label="Text input with formatter (on input)"
-      label-for="input-formatter"
-      description="We will convert your name to lowercase instantly"
-      class="mb-0"
-    >
-      <gl-form-input
-        id="input-formatter"
-        v-model="text1"
-        placeholder="Enter your name"
-        :formatter="formatter"
-      ></gl-form-input>
-    </gl-form-group>
-    <p><b>Value:</b> {{ text1 }}</p>
-
-    <gl-form-group
-      label="Text input with lazy formatter (on blur)"
-      label-for="input-lazy"
-      description="This one is a little lazy!"
-      class="mb-0"
-    >
-      <gl-form-input
-        id="input-lazy"
-        v-model="text2"
-        placeholder="Enter your name"
-        lazy-formatter
-        :formatter="formatter"
-      ></gl-form-input>
-    </gl-form-group>
-    <p class="mb-0"><b>Value:</b> {{ text2 }}</p>
-  </div>
-</template>
-
-<script>
-  export default {
-    data() {
-      return {
-        text1: '',
-        text2: ''
-      }
-    },
-    methods: {
-      formatter(value) {
-        return value.toLowerCase()
-      }
-    }
-  }
-</script>
-```
-
-**Note:** When using a non-text-like input (i.e. `color`, `range`, `date`, `number`, `email` etc.),
-ensure that your formatter function returns the value in the expected format
-(`date` -> '2000-06-01', `color` -> '#ff0000', etc.) for the input type.
-The formatter **must** return the value as a _string_.
-
-**Note:** With non-lazy formatting, if the cursor is not at the end of the input value,
-the cursor may jump to the end _after_ a character is typed. You can use the provided event
-object and the `event.target` to access the native input's selection methods and properties
-to control where the insertion point is.
-
-## Readonly plain text
-
-If you want to have `<gl-form-input readonly>` elements in your form styled as plain text,
-set the `plaintext` prop (no need to set `readonly`) to remove the default form field
-styling and preserve the correct margin and padding.
-
-The `plaintext` option is not supported by input types `color` or `range`.
-
-## Disabled mousewheel events on numeric-like inputs
-
-On some browsers, scrolling the mousewheel while a numeric-like input is focused will
-increment or decrement the input's value. Therefore, mousewheel events are disabled on
-focus numeric type inputs.
-
-## `v-model` modifiers
-
-Vue does not officially support `.lazy`, `.trim`, and `.number` modifiers on the `v-model`
-of custom component based inputs, and may generate a bad user experience.
-Avoid using Vue's native modifiers.
-
-To get around this, `<gl-form-input>` has three boolean props `trim`, `number`,
-and `lazy` which emulate the native Vue `v-model` modifiers `.trim` and `.number`
-and `.lazy` respectively. The `lazy` prop will update the v-model on `change`/`blur` events.
-
-**Notes:**
-
-- The `number` prop takes precedence over the `trim` prop
-(i.e. `trim` will have no effect when `number` is set).
-- When using the `number` prop, and if the value can be parsed as a number (via `parseFloat`)
-it will return a value of type `Number` to the `v-model`, otherwise the original input value
-is returned as type `String`. This is the same behaviour as the native `.number` modifier.
-- The `trim` and `number` modifier props do not affect the value returned by the
-`input` or `change` events. These events will always return the string value of the
-content of `<textarea>` after optional formatting (which may not match the value returned
-via the `v-model` `update` event, which handles the modifiers).
-
-## Debounce support
-
-As an alternative to the `lazy` modifier prop, `<gl-form-input>` optionally supports debouncing
-user input, updating the `v-model` after a period of idle time from when the last character
-was entered by the user (or a `change` event occurs). If the user enters a new character
-(or deletes characters) before the idle timeout expires, the timeout is re-started.
-
-To enable debouncing, set the prop `debounce` to any integer greater than zero.
-The value is specified in milliseconds. Setting `debounce` to `0` will disable debouncing.
-
-Note: debouncing will _not_ occur if the `lazy` prop is set.
-
-## Autofocus
-
-When the `autofocus` prop is set, the input will be auto-focused when it is inserted
-(i.e. **mounted**) into the document, or re-activated when inside a Vue `<keep-alive>` component.
-Note that this prop **does not** set the `autofocus` attribute on the input,
-nor can it tell when the input becomes visible.
-
-## Native and custom events
-
-All native events (other than the custom `input` and `change` events) are supported,
-without the need for the `.native` modifier.
-
-The custom `update` and `change` events receive a single argument of the current `value`
-(after any formatting has been applied), and are triggered by user interaction.
-
-The custom `input` event is passed the input value, and is emitted whenever the
-`v-model` needs updating (it is emitted before `update`, `change`. and `blur` as needed).
-
-You can always access the native `input` and `change` events by using the `.native` modifier.
-
-## Exposed input properties and methods
-
-`<gl-form-input>` exposes several of the native input element's properties and methods
-on the component reference (i.e. assign a `ref` to your `<gl-form-input ref="foo" ...>`
-and use `this.$refs['foo'].propertyName` or `this.$refs['foo'].methodName(...)`).
-
-### Input properties
-
-| Property              | Notes      |
-| --------------------- | ---------- |
-| `.selectionStart`     | Read/Write |
-| `.selectionEnd`       | Read/Write |
-| `.selectionDirection` | Read/Write |
-| `.validity`           | Read only  |
-| `.validationMessage`  | Read only  |
-| `.willValidate`       | Read only  |
-
-### Input methods
-
-| Method                 | Notes                             |
-| ---------------------- | --------------------------------- |
-| `.focus()`             | Focus the input                   |
-| `.blur()`              | Remove focus from the input       |
-| `.select()`            | Selects all text within the input |
-| `.setSelectionRange()` |                                   |
-| `.setRangeText()`      |                                   |
-| `.setCustomValidity()` |                                   |
-| `.checkValidity()`     |                                   |
-| `.reportValidity()`    |                                   |
-
-Refer to <https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement> for more
-information on these methods and properties. Support will vary based on input type.

package/src/components/base/form/form_radio/form_radio.md

@@ -1,23 +0,0 @@
-`GlFormRadio` components can be used directly, or via a `GlFormRadioGroup`.
-
-Below is an example which demonstrates the direct approach. For examples using
-`GlFormRadioGroup`, see the documentation for that component.
-
-```html
-<script>
-  export default {
-    data() {
-      return {
-        selected: 'yes',
-      };
-    },
-  };
-</script>
-
-<template>
-  <div>
-    <gl-form-radio v-model="selected" value="yes">Yes</gl-form-radio>
-    <gl-form-radio v-model="selected" value="no">No</gl-form-radio>
-  </div>
-</template>
-```

package/src/components/base/form/form_radio_group/form_radio_group.md

@@ -1,63 +0,0 @@
-The `GlFormRadioGroup` component provides an alternative and sometimes more
-compact way of setting up a group of `GlFormRadio` components.
-
-## Usage
-
-`GlFormRadioGroup` can be used in a few ways to build a group of `GlFormRadio`
-components: implicitly, explicitly, or a mix of both.
-
-Below is an example which demonstrates all three approaches, written such that
-all of them produce the same visual result.
-
-```html
-<script>
-export default {
-  data() {
-    return {
-      selected: 'one',
-      options: [
-        {
-          value: 'one',
-          text: 'One',
-        },
-        {
-          value: 'two',
-          text: 'Two',
-        },
-        {
-          value: 'three',
-          text: 'Three',
-        },
-      ],
-    };
-  },
-};
-</script>
-
-<template>
-  <div>
-    <!-- Implicit -->
-    <gl-form-radio-group v-model="selected" :options="options" name="implicit" />
-
-    <!-- Explicit -->
-    <gl-form-radio-group v-model="selected" name="explicit">
-      <gl-form-radio value="one">One</gl-form-radio>
-      <gl-form-radio value="two">Two</gl-form-radio>
-      <gl-form-radio value="three">Three</gl-form-radio>
-    </gl-form-radio-group>
-
-    <!-- Mixed -->
-    <gl-form-radio-group v-model="selected" :options="[options[1]]" name="mixed">
-      <template #first>
-        <gl-form-radio value="one">One</gl-form-radio>
-      </template>
-      <gl-form-radio value="three">Three</gl-form-radio>
-    </gl-form-radio-group>
-  </div>
-</template>
-```
-
-## Stacked
-
-By default, the GitLab Design guide mandates the `<gl-form-radio-group>` be `stacked` by default and
-is non-changeable at this time.

package/src/components/base/form/form_select/form_select.md

@@ -1 +0,0 @@
-Form select component used to select from group of options in a form.

package/src/components/base/form/form_textarea/form_textarea.md

@@ -1,3 +0,0 @@
-**Note:** This needs a `v-model` property to work correctly.
-See [this issue](https://github.com/bootstrap-vue/bootstrap-vue/issues/1915) on Bootstrap Vue for
-more information.

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

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