@gitlab/ui 115.9.0 → 115.9.2

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).

package/src/components/base/infinite_scroll/infinite_scroll.md

@@ -1,104 +0,0 @@
-## Usage
-
-The infinite scroll component wraps around a results list and emits a message
-(`bottomReached`) when the bottom of the viewport is reached, which should trigger
-a re-fetching. The `gl-infinite-scroll` component expects its parent component to
-manage the re-fetching.
-
-Additionally it emits a `topReached` message when the top of the viewport is reached, which
-can be useful to load items on top of the available data. If only `topReached` is present, the
-viewport will be scrolled to the bottom the first time this component is mounted.
-
-## Public methods
-
-Useful public methods you can call via `$refs`:
-
-- `.scrollUp()`: Scrolls to the top of the container.
-- `.scrollDown()`: Scrolls to the bottom of the container.
-- `.scrollTo({ top, behavior })`: Scrolls to a number of pixels
-  along the Y axis of the container. The scrolling behavior can also be specified,
-  as per MDN spec (<https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollTo>)
-
-## Implementation Example
-
-This is how a full implementation would look like with paginated results from GitLab's
-`projects` API.
-
-In the component's state, initialize a `pageInfo` object:
-
-```js
-pageInfo: {
-  currentPage: 0,
-  nextPage: 0,
-  totalPages: 0,
-  totalResults: 0,
-}
-```
-
-When fetching for the first time, set the state with the header
-information in the mutations:
-
-```html
-Vue.set(state.pageInfo, 'currentPage', parseInt(headers['X-Page'], 10));
-Vue.set(state.pageInfo, 'nextPage', parseInt(headers['X-Next-Page'], 10));
-Vue.set(state.pageInfo, 'totalPages', parseInt(headers['X-Total-Pages'], 10));
-Vue.set(state.pageInfo, 'totalResults', parseInt(headers['X-Total'], 10));
-```
-
-_Note: There is a function you can use for parsing integers in headers in
-GitLab called `parseIntPagination` in `common/utils.js`_
-
-Every time `bottomReached` happens, update the state in your mutations:
-
-```js
-state.searchResults = state.searchResults.concat(results.data);
-Vue.set(state.pageInfo, 'nextPage', parseInt(headers['X-Next-Page'],10));
-Vue.set(state.pageInfo, 'totalPages', parseInt(headers['X-Total-Pages'],10));
-```
-
-Use the state to fetch the next page in the actions. In this case, the `Projects`
-API allows us to send in a `page` parameter to fetch a certain page from the
-list of results.
-
-```js
-export const fetchNextPage = ({ state, dispatch }) => {
-  if(state.pageInfo.currentPage < state.pageInfo.totalPages) {
-    Api.projects(searchQuery, { page: state.pageInfo.nextPage })
-      ...
-  }
-};
-```
-
-```html
-<script>
-exportDefault {
-  components: {
-    GlInfiniteScroll,
-  },
-  computed: {
-    ...mapState([
-      'pageInfo',
-      'searchResults',
-    ]),
-  },
-  methods: {
-    ...mapActions([
-      'fetchNextPage',
-    ]),
-    bottomReached() {
-      this.fetchNextPage();
-    },
-  },
-}
-</script>
-<template>
-  <gl-infinite-scroll
-    @bottomReached="bottomReached"
-    :max-list-height="400"
-    :fetched-items="searchResults.length"
-    :total-items="totalResults"
-  >
-    ...Results in a list, another component, etc ....
-  </gl-infinite-scroll>
-</template>
-```

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

@@ -1,49 +0,0 @@
-Pagination is used to help users parse a large number of items on a page,
-whenever there are too many results to show at once. Pagination breaks up
-results into several pages with controls for navigating forward and backward, or
-to a specific page.
-
-## Usage
-
-The simplest way to use `GlKeysetPagination` with a paginated GraphQL response
-is to `v-bind` to the
-[`PageInfo`](https://docs.gitlab.com/ee/api/graphql/reference/#pageinfo) type
-returned by the endpoint:
-
-```html
-<gl-keyset-pagination v-bind="pageInfo" />
-```
-
-This is possible because the default field names of the `PageInfo` type align
-with the `props` of this component.
-
-## Dos and don'ts
-
-**✅ Do** provide the `prevText` and `nextText` props with translatable strings.
-The default strings ("Prev" and "Next") are hardcoded in this component and
-can't be translated.
-
-Example:
-
-```html
-<gl-keyset-pagination v-bind="pageInfo" :prev-text="__('Prev')" :next-text="__('Next')" />
-```
-
-**✅ Do** use this component for paginating GraphQL requests[^1] (or any
-endpoint that uses keyset pagination).
-
-**❌ Don't** use this component for paginating REST requests[^1] (or any
-endpoint that uses offset pagination).
-
-For offset pagination, use the [`GlPagination`
-component](/?path=/story/base-pagination--default) instead.
-
-For more information on the difference between offset and keyset pagination see
-[our documentation on GraphQL
-pagination](https://docs.gitlab.com/ee/development/graphql_guide/pagination.html).
-
-[^1]: There's no intrinsic reason why GraphQL endpoints can't support offset pagination (in fact, [the official documentation](https://graphql.org/learn/pagination/#pagination-and-edges) shows an example offset pagination implementation) or why REST endpoints can't support keyset pagination. This is simply how we've chosen to implement our REST and GraphQL endpoints at GitLab.
-
-## Pajamas reference
-
-<https://design.gitlab.com/components/pagination>

package/src/components/base/label/label.md

@@ -1,15 +0,0 @@
-Labels are editable objects that allow users to manually categorize other objects, like issues,
-merge requests, and epics. They have a name, description, and a customizable background color.
-They provide a quick way to recognize which categories the labeled object belongs to.
-
-## Using the component
-
-```js
-<gl-label
-  background-color="#D9C2EE"
-  title="Label content"
-  description="Some content"
-  tooltipPlacement="top"
-  target="http://some.url"
-/>
-```

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).