@gitlab/ui 115.9.0 → 115.9.1

package/src/components/base/link/link.md

@@ -1,187 +0,0 @@
-## Variants
-
-- **Inline**: Link that appears within body text, like a paragraph or sentence. In order to
-  distinguish a linked reference from surrounding content, a link within body copy must be
-  underlined. Inline text links can be user-generated, for example, referencing an issue with
-  "#3126" in the markdown editor of a merge request description where the link's primary function
-  is linking to the referred issue. They can also be in text generated from a source file, for
-  example, a "learn more about pipelines" link in the paragraph of an empty state template.
-- **User interface (UI)**: Standalone link in the UI. User interface links are not user-generated.
-  For example, a link in the system notes that compares the changes in a new commit to a previous
-  one. The placement, color, and actionable text all provide link affordance. A link button has a
-  similar style, but is used for an action and not a link.
-- **Meta**: Standalone text or text within a short string of system-generated content may contain
-  multiple meta links. Meta links share a meaningful datapoint or reference, and are only links
-  secondarily. For example, the primary function of including "%15.8" in a string is to
-  communicate the milestone, though it can also link to more information about it. Meta links represent
-  a wide variety of content and should be styled specifically for the contexts in which they appear.
-- **Mention**: Indicates when a user is "@" mentioned in the content. The username links to the
-  user's profile. A mention link can be within body or meta content.
-
-Use `<gl-link>` to render links. It can render standard `<a>` elements,
-and also Vue Router and Nuxt links.
-
-```html
-<gl-link href="#foo">Link</gl-link>
-```
-
-## External link indicator
-
-The `show-external-icon` prop displays a "↗" character after the link text to indicate external links.
-This feature is available for **inline**, **UI (default)**, and **meta** variants only.
-
-```html
-<!-- External link with indicator -->
-<gl-link href="https://kubernetes.io/docs" target="_blank" show-external-icon>
-  Kubernetes documentation
-</gl-link>
-<!-- Renders as: Kubernetes documentation ↗ -->
-
-<!-- Different variants with external indicator -->
-<gl-link variant="inline" href="https://prometheus.io" target="_blank" show-external-icon>
-  Learn more about Prometheus monitoring
-</gl-link>
-
-<gl-link variant="meta" href="https://docker.com" target="_blank" show-external-icon>
-  Docker Hub
-</gl-link>
-```
-
-**Requirements for the external icon to appear:**
-
-- `show-external-icon` prop must be `true`.
-- `href` prop must be provided.
-- `target="_blank"` must be set.
-- Destination domain must be [determined as external](https://gitlab.com/gitlab-org/gitlab-services/design.gitlab.com/-/blob/b5e4b0b4241455ed0fa45e0f6f5b83a3b76755ff/packages/gitlab-ui/src/directives/safe_link/safe_link.js#L12).
-- Link variant must be `inline`, `meta`, or default (UI).
-
-**Note:** The external icon is not available for `mention` or `unstyled` variants as these have
-specific design purposes that don't align with external link indication.
-
-## Link type
-
-By specifying a value in the `href` prop, a standard link (`<a>`) element will be rendered. To
-generate a `<router-link>` instead, specify the route location via the `to` prop.
-
-### Router links
-
-Router links support various additional props.
-
-If your app is running under [Nuxt.js](https://nuxtjs.org), the
-[`<nuxt-link>`](https://nuxtjs.org/api/components-nuxt-link) component will be used instead of
-`<router-link>`. The `<nuxt-link>` component supports all the same features as `<router-link>` (as
-it is a wrapper component for `<router-link>`) and more.
-
-#### `to`
-
-- type: `string | Location`
-- required to generate a `<router-link>`
-
-Denotes the target route of the link. When clicked, the value of the `to` prop will be passed to
-`router.push()` internally, so the value can be either a string or a location descriptor object.
-
-```html
-<!-- Literal string -->
-<gl-link to="home">Home</gl-link>
-<!-- Renders to -->
-<a href="home">Home</a>
-
-<!-- Omitting `v-bind` is fine, just as binding any other prop -->
-<gl-link :to="'home'">Home</gl-link>
-
-<!-- Same as above -->
-<gl-link :to="{ path: 'home' }">Home</gl-link>
-
-<!-- Named route -->
-<gl-link :to="{ name: 'user', params: { userId: 123 } }">User</gl-link>
-
-<!-- With query, resulting in `/register?plan=private` -->
-<gl-link :to="{ path: 'register', query: { plan: 'private' } }">Register</gl-link>
-
-<!-- Render a non-router link by omitting `to` and specifying an `href` -->
-<gl-link href="/home">Home</gl-link>
-```
-
-#### `replace`
-
-- type: `boolean`
-- default: `false`
-
-Setting `replace` prop will call `router.replace()` instead of `router.push()` when clicked, so the
-navigation will not leave a history record.
-
-```html
-<gl-link :to="{ path: '/abc'}" replace></gl-link>
-```
-
-#### `active-class`
-
-- type: `string`
-- default: `'router-link-active'` (`'nuxt-link-active'` when using Nuxt.js)
-
-Configure the active CSS class applied when the link is active. Note the default value can also be
-configured globally via the `linkActiveClass`
-[router constructor option](https://router.vuejs.org/api/#linkactiveclass).
-
-With components that support router links (have a `to` prop), you will want to set this to the class
-`'active'` (or a space separated string that includes `'active'`) to apply Bootstrap's active
-styling on the component when the current route matches the `to` prop.
-
-#### `exact-active-class`
-
-- type: `string`
-- default: `'router-link-exact-active'` (`'nuxt-link-exact-active'` when using Nuxt.js)
-- availability: Vue Router 2.5.0+
-
-Configure the active CSS class applied when the link is active with exact match. Note the default
-value can also be configured globally via the `linkExactActiveClass`
-[router constructor option](https://router.vuejs.org/api/#linkexactactiveclass).
-
-With components that support router links (have a `to` prop), you will want to set this to the class
-`'active'` (or a space separated string that includes `'active'`) to apply Bootstrap's active
-styling on the component when the current route matches the `to` prop.
-
-## Links with `href="#"`
-
-Typically `<a href="#">` will cause the document to scroll to the top of page when clicked.
-`<gl-link>` addresses this by preventing the default action (scroll to top) when `href` is set to
-`#`.
-
-If you need scroll to top behaviour, use a standard `<a href="#">...</a>` tag.
-
-## Link disabled state
-
-Disable link functionality by setting the `disabled` prop to true.
-
-```html
-<gl-link href="#foo" disabled>Disabled Link</gl-link>
-```
-
-Disabling a link handles stopping event propagation, preventing the default action from occurring,
-and removing the link from the document tab sequence (`tabindex="-1"`).
-
-## Security
-
-This component implements a few security measures to make it as safe as possible by default.
-See [SafeLinkDirective docs] for more details.
-
-### Linking to an unsafe URL
-
-If you're trying to link to a location considered unsafe by the `SafeLink` directive (when rendering
-a download link with a [Data URL] for example), you'll need to bypass the `href` attribute's
-sanitization. This component exposes the `is-unsafe-link` prop for that purpose.
-
-> **Warning:** Only disable URL sanitization when absolutely necessary.
-
-```html
-<gl-link
-  is-unsafe-link
-  download="file.txt"
-  href="data:text/plain;charset=utf-8,GitLab%20is%20awesome"
->
-  Download
-</gl-link>
-```
-
-[SafeLinkDirective docs]: https://design.gitlab.com/storybook?path=/docs/directives-safe-link-directive--default
-[Data URL]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs

package/src/components/base/loading_icon/loading_icon.md

@@ -1,3 +0,0 @@
-## Under the hood
-
-Loading icon uses pure css to render a spinner or an ellipsis loader.

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

@@ -1,30 +0,0 @@
-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.
-
-## VModel
-
-You can use the `v-model` directive to control the modal’s visibility. The `v-model`
-directive interfaces with the `visible` property and the `@change` event.
-
-## Deprecation Warning
-
-We are deprecating the `modal-ok` and `modal-cancel` slots. We are also changing the way the
-`modal-footer` slot content is populated. This is in order to align this component with the design
-system.
-
-The `modal-footer` slot should only be populated via props: `action-primary`, `action-secondary` and
-`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
-{
-  text: 'Save Changes',
-  attributes: {
-    variant: 'confirm',
-    disabled: this.someState,
-    class: 'some-class',
-    ...
-  }
-}
-```

package/src/components/base/new_dropdowns/disclosure/disclosure_dropdown.md

@@ -1,184 +0,0 @@
-A disclosure dropdown is a button that toggles a panel containing a list of actions and/or links. Use
-[this decision tree](https://design.gitlab.com/components/dropdown-overview#which-component-should-you-use)
-to make sure this is the right dropdown component for you.
-
-## Basic usage
-
-```html
-<gl-disclosure-dropdown toggle-text="Actions" :items="items" />
-```
-
-## Icon-only disclosure dropdown
-
-Icon-only disclosure dropdowns must have an accessible name.
-You can provide this with the combination of `toggleText` and `textSrOnly` props.
-
-Optionally, you can use `no-caret` to remove the caret and `category="tertiary"` to remove the border.
-
-```html
-<gl-disclosure-dropdown
-  icon="ellipsis_v"
-  toggle-text="Actions"
-  text-sr-only
-  category="tertiary"
-  no-caret
-/>
-```
-
-## Opening the disclosure dropdown
-
-Disclosure dropdown will open on toggle button click (if it was previously closed).
-On open, `GlDisclosureDropdown` will emit the `shown` event.
-
-## Closing the disclosure dropdown
-
-The disclosure dropdown is closed by any of the following:
-
-- pressing <kbd>Esc</kbd>
-- clicking anywhere outside the component
-- clicking the action or link inside the dropdown
-
-Before closing, `GlDisclosureDropdown` emits a `beforeClose` event with these properties:
-
-1. `originalEvent` – the event that triggered closing of the dropdown
-2. `preventDefault` – a method which will prevent closing of the dropdown
-
-An example of using this event to prevent the dropdown from closing:
-
-```html
-<gl-disclosure-dropdown @beforeClose="$event.preventDefault()" />
-```
-
-Note that this method will also prevent the dropdown from closing even if the trigger button is clicked.
-
-You can use the `preventDefault` to filter out events that are causing undesired dropdown closing:
-
-```html
-<gl-disclosure-dropdown
-  @beforeClose="(e) => { ignoreElement.contains(e.originalEvent.target) && e.preventDefault() }"
-/>
-```
-
-After closing, `GlDisclosureDropdown` emits a `hidden` event.
-
-### Closing the disclosure dropdown programmatically
-
-It's possible to close the disclosure dropdown programmatically by calling the `closeAndFocus` or
-`close` methods on the disclosure dropdown via a template ref. For example:
-
-```js
-this.$refs.disclosureDropdown.closeAndFocus();
-```
-
-The `closeAndFocus` method is preferred in most cases, especially when triggering it from some action
-within the disclosure dropdown, because it will move focus back to the disclosure dropdown trigger.
-
-The `close` method should only be used when closing the disclosure dropdown and moving the focus to
-some other element. For example, closing the disclosure dropdown to focus a newly revealed text input.
-
-## Setting disclosure dropdown items
-
-Use the `items` prop to provide actions/links to the disclosure dropdown. Each
-item can be either an item or a group. For `Item`s, provide an `href` or `to` string or
-[`to` location descriptor object](https://v3.router.vuejs.org/api/#to) to
-make them render as links. Otherwise, they will be buttons. Provide an `action`
-function to items to be called when they are pressed, or, listen for the
-`action` event on the top-level component. Both will receive the given item as
-an argument.
-A [validation error](https://gitlab.com/gitlab-org/gitlab-ui/-/blob/6cbff4f908b429cc01f17a4cc2868e881db1aa31/src/components/base/new_dropdowns/disclosure/utils.js#L1)
-will be triggered if neither field is set.
-
-Below are the expected shapes of these objects:
-
-```typescript
-type Item = {
-  // The item text
-  text: string;
-  // href link
-  href?: string;
-  // or, a Vue router link with `to`
-  // See https://github.com/vuejs/vue-router/blob/v3.6.5/types/router.d.ts#L400-L408 for Location definition
-  to?: string | Location;
-  // Item action
-  action?: (item: Item) => void;
-  // Set of extra attributes applied directly to the element
-  extraAttrs?: Object;
-  // Additional class/classes applied to the item wrapper
-  wrapperClass?: string;
-};
-
-type Group = {
-  // Name of the group, used as a header
-  name?: string;
-  // Items of the group
-  items: Array<Item>;
-  // Set of extra attributes applied directly to the element
-  extraAttrs?: Object;
-};
-
-type ItemsProp = Array<Item> | Array<Group>;
-```
-
-### Actions/links
-
-The `text` property is used to render the default disclosure dropdown item
-template. If you want to render a custom template for items, use the
-`list-item` scoped slot:
-
-```html
-<gl-disclosure-dropdown :items="items">
-  <template #list-item="{ item }">
-    <span class="gl-flex gl-items-center gl-justify-between">
-      {{item.text}}
-      <gl-icon v-if="item.icon" :name="item.icon" />
-    </span>
-  </template>
-</gl-disclosure-dropdown>
-```
-
-### Groups
-
-Actions/links can be contained within groups. A group can have a `name`
-property, which will be used as the group header if present.
-It also has a required property `items` that must be an array of links/actions.
-
-Groups can be at most one level deep: a group can only contain actions/links.
-Items and groups _cannot_ be siblings. Either all items are actions/links,
-or they are all groups.
-
-To render custom group labels, use the `group-label` scoped slot:
-
-```html
-<gl-disclosure-dropdown :items="groups">
-  <template #group-label="{ group }">
-    {{ group.name }} <gl-badge size="sm">{{ group.items.length }}</gl-badge>
-  </template>
-</gl-disclosure-dropdown>
-```
-
-To draw a horizontal line that separates two groups, set the `bordered` property.
-By default, the border appears above the group. You can change the border position
-using the `border-position` property:
-
-```html
-<gl-disclosure-dropdown>
-  <gl-disclosure-dropdown-group bordered border-position="bottom" :group="group" />
-</gl-disclosure-dropdown>
-```
-
-### Miscellaneous content
-
-Besides default components, disclosure dropdown can render miscellaneous content inside it.
-In this case the user is responsible for handling all events and navigation inside the disclosure.
-
-### Dealing with long option texts
-
-- Some options might have long non-wrapping text that would overflow the dropdown maximum width. In
-  such cases, it's recommended to override the `#list-item` slot and to truncate the option text using
-  `GlTruncate`.
-- If the toggle text reflects the selected option text, it might be necessary to truncate
-  it too by overriding the `#toggle` slot.
-
-## Split dropdown
-
-See [button group documentation](/docs/base-button-group--docs#split-dropdowns).

package/src/components/base/new_dropdowns/listbox/listbox.md

@@ -1,195 +0,0 @@
-A collapsible listbox is a button that toggles a panel containing a list of options.
-It supports single and multi-selection.
-
-**Single-select:** By default, selecting an option will update the toggle label with the choice.
-But the custom toggle text can be provided.
-When option is selected, the dropdown will be closed and focus set on the toggle button.
-
-**Multi-select:** Selecting an option will not update the toggle, but it can be customized
-providing `toggleText` property. Also, selecting or deselecting an item won't close the dropdown.
-
-## Icon-only listbox
-
-Icon-only listboxes must have an accessible name.
-You can provide this with the combination of `toggleText` and `textSrOnly` props.
-For single-select listboxes `toggleText` will be set to the selected item's `text` property value
-by default.
-
-Optionally, you can use `no-caret` to remove the caret and `category="tertiary"` to remove the border.
-
-```html
-<gl-collapsible-listbox
-  icon="ellipsis_v"
-  toggle-text="More options"
-  text-sr-only
-  category="tertiary"
-  no-caret
->
-```
-
-## Labeling the listbox
-
-The `toggleId` prop sets the `id` of the toggle element. This is useful for associating a label
-element with the toggle.
-
-```html
-<gl-form-group label="Department" label-for="department-picker">
-  <gl-collapsible-listbox
-    toggle-id="department-picker"
-    :items="departments"
-  />
-</gl-form-group>
-```
-
-Prefer using `toggleId` over `toggleAriaLabelledBy`, as it is more similar to how
-label elements are associated with other form components.
-
-**Note:** Do not use the `toggleId` prop in conjunction with the `toggle` slot.
-Instead, set the `id` directly on the custom toggle element, and pass the same
-value to `GlFormGroup`'s `labelFor` prop.
-
-## Opening the listbox
-
-Listbox will open on toggle button click (if it was previously closed).
-On open, `GlCollapsibleListbox` will emit the `shown` event.
-
-## Closing the listbox
-
-The listbox is closed by any of the following:
-
-- pressing <kbd>Esc</kbd>
-- clicking anywhere outside the component
-- selecting an option in single-select mode
-
-After closing, `GlCollapsibleListbox` emits a `hidden` event.
-
-### Closing the listbox programmatically
-
-It's possible to close the listbox programmatically by calling the `closeAndFocus` or `close` methods
-on the listbox via a template ref. For example:
-
-```js
-this.$refs.listbox.closeAndFocus()
-```
-
-The `closeAndFocus` method is preferred in most cases, especially when triggering it from some action
-within the listbox, because it will move focus back to the listbox trigger.
-
-The `close` method should only be used when closing the listbox and moving the focus to some other element.
-For example, closing the listbox to focus a newly revealed text input.
-
-## Selecting items
-
-Set the `v-model` on the listbox to have 2-way data binding for the selected items in the listbox.
-Alternatively, you can set `selected` property to the array of selected items
-`value` properties (for multi-select) or to the selected item `value` property for a single-select.
-On selection the listbox will emit the `select` event with the selected values.
-
-## Resetting the selection
-
-`GlCollapsibleListbox` can render a reset button if the `headerText` and
-`resetButtonLabel` props are provided.
-When clicking on the reset button, a `reset` event is emitted. It is the consumer's responsibility
-to listen to that event and to update the model as needed.
-
-## Setting listbox options
-
-Use the `items` prop to provide options to the listbox. Each item can be
-either an option or a group. Below are the expected shapes of these
-objects:
-
-```typescript
-type Option = {
-  value: string | number | null
-  text?: string
-}
-
-type Group = {
-  text: string
-  options: Array<Option>
-  textSrOnly?: boolean
-}
-
-type ItemsProp = Array<Option> | Array<Group>
-```
-
-### Options
-
-The `value` property of options must be unique across all options
-provided to the listbox, as it's used as a primary key.
-
-The optional `text` property is used to render the default listbox item
-template. If you want to render a custom template for items, use the
-`list-item` scoped slot:
-
-```html
-<gl-collapsible-listbox :items="items">
-  <template #list-item="{ item }">
-    <span class="gl-flex gl-items-center">
-      <gl-avatar :size="32" class-="gl-mr-3"/>
-      <span class="gl-flex gl-flex-col">
-        <span class="gl-font-bold gl-whitespace-nowrap">{{ item.text }}</span>
-        <span class="gl-text-subtle"> {{ item.secondaryText }}</span>
-      </span>
-    </span>
-  </template>
-</gl-collapsible-listbox>
-```
-
-### Groups
-
-Options can be contained within groups. A group has a required `text`
-property, which must be unique across all groups within the listbox, as
-it's used as a primary key. It also has a required property `items` that
-must be an array of options. Optionally, you can hide the group heading
-by setting `textSrOnly` to `true`. In this case the `text` is only used
-for accessibility purposes.
-
-Groups can be at most one level deep: a group can only contain options.
-Options and groups _cannot_ be siblings. Either all items are options,
-or they are all groups.
-
-To render custom group labels, use the `group-label` scoped slot:
-
-```html
-<gl-collapsible-listbox :items="groups">
-  <template #group-label="{ group }">
-    {{ group.text }} <gl-badge size="sm">{{ group.options.length }}</gl-badge>
-  </template>
-</gl-collapsible-listbox>
-```
-
-### Dealing with long option texts
-
-- Some options might have long non-wrapping text that would overflow the dropdown maximum width. In
-such cases, it's recommended to override the `#list-item` slot and to truncate the option text using
-`GlTruncate`.
-- If the toggle text reflects the selected option text, it might be necessary to truncate
-it too by overriding the `#toggle` slot.
-
-## Search
-
-To filter out items by  search query set `searchable` property to `true`.
-Listbox will render the search field and will emit `search` event with the `searchQuery` value.
-Performing the search is the responsibility of the listbox's consumer component.
-When performing search set `searching` prop to `true` - this will render the loader
-while search is in progress instead of the list of items.
-To update content of the listbox, toggle the `searching` property
-and update the `items` property with a new array. Be sure to debounce (or
-similar) the `search` event handler to avoid rendering stale results.
-To improve the accessibility, provide the `search-summary-sr-only` scoped slot
-with a number of found search results text, alternately, you can pass a plural translate function.
-An example of the plural translate function can be found [the GitLab Docs internationalization section](https://docs.gitlab.com/ee/development/i18n/externalization.html#plurals)
-Screen reader will announce this text when the list is updated.
-
-```html
-<gl-collapsible-listbox :items="items" searchable>
-  <template #search-summary-sr-only>
-    5 users found
-  </template>
-</gl-collapsible-listbox>
-```
-
-## Split dropdown
-
-See [button group documentation](/docs/base-button-group--docs#split-dropdowns).

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

@@ -1,45 +0,0 @@
-## Current page
-
-The current page's value should be bound using `v-model`, e.g.:
-
-```html
-<script>
-  export default {
-    data: () => ({
-      page: 2,
-    }),
-  };
-</script>
-
-<template>
-  <gl-pagination v-model="page" :per-page="10" :total-items="100" />
-</template>
-```
-
-## Limits
-
-The `limits` prop is used to define pagination link limits based on Bootstrap's breakpoint sizes.
-It is strongly recommended you provide a 'default' property, even if you have accounted for all
-breakpoint sizes. While unlikely, it is possible breakpoints could change, thus, a default property
-ensures a graceful fallback.
-
-Here is `limits` default value:
-
-```js
-{
-  xs: 0,
-  sm: 3,
-  md: 9,
-  default: 9,
-}
-```
-
-> Note: The component will not render any UI if the total items available for display is less than
-> the max items per page.
-
-## Internet Explorer 11
-
-This component makes use of the
-[`Number.isInteger` method](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isInteger),
-which is not supported in IE11, make sure it's being polyfilled when using the component.
-[`core-js`](https://github.com/zloirock/core-js) incudes the appropriate polyfill for this.

package/src/components/base/path/path.md

@@ -1,41 +0,0 @@
-## Usage
-
-Paths are horizontal process flows composed of a series of "stages".
-Like tabs, paths let users focus in on specific content at each stage
-whilst still keeping all the other stages in view. Only one stage can
-be active at a given time.
-
-### Implemetation
-
-The component should be initialized with an array of data objects. By
-default, the first item in the array will be selected. This can be
-overridden by passing in an object with the selected property set to
-true.
-
-```js
-items: [
-  {
-    title: 'First',
-  },
-  {
-    title: 'Second',
-    selected: true
-  },
-  ...
-```
-
-Once an item has been selected the `selected` event will be emitted.
-The emitted event will include the entire object at the selected index.
-
-#### Customization
-
-Additional attributes can be configured via the `items` object. Currently
-support for `metric` and `icon` are provided. Please see the individual
-examples for further information on these.
-
-### Additional information
-
-A `backgroundColor` property can be specified when using this component
-on different colored backgrounds.
-
-This component supports various themes and is mobile responsive.