@gitlab/ui 115.9.0 → 115.9.1

package/src/components/base/breadcrumb/breadcrumb.md

@@ -1,52 +0,0 @@
-## Usage
-
-The `GlBreadcrumb` component comes with a smart auto-resize feature. When there is not enough space
-to show all breadcrumb `items` in a single row, the component moves items into an ellipsis dropdown,
-starting with the first one. The last breadcrumb item (which represents the current page) stays
-always visible.
-
-### Auto-resize
-
-**Important:** For the auto-resize to function correctly it is necessary that the `GlBreadcrumb`
-component itself takes all the horizontal space it can get. How to do this depends on the
-CSS `display` mode (block, flex, grid) of its parent element.
-
-**Example:** In a flexbox layout, allow the component to `flex-grow`:
-
-```js
-<gl-breadcrumb class="gl-grow" :items="items" />
-```
-
-### `items` prop
-
-This component also allows for optional avatars on each item.
-
-`avatarPath` should passed along with `text` and `href` in `items`.
-Here is an example of how an item with an avatar should look:
-
-**note:** the component supports passing the property `to` in the list items to enable navigation
-through `vue-router`
-
-#### Example
-
-```js
-items = [
-  {
-    text: 'First item',
-    href: '#',
-    avatarPath: '/avatar.png',
-  },
-];
-
-<gl-breadcrumb :items="items" />
-```
-
-### `size` prop
-
-The size prop determines the size of the breadcrumb component. It accepts the following values:
-
-"sm" (default): Small size
-"md": Medium size
-
-Using the default 'sm' size for all page breadcrumbs is considered a best practice
-to ensure consistency across the application.

package/src/components/base/broadcast_message/broadcast_message.md

@@ -1,25 +0,0 @@
-Broadcast messages provide an efficient and prominent way to deliver critical messages at the
-instance level to all users. For example, a broadcast message can be used when an admin wants to
-announce that their platform will experience downtime during a specific period.
-
-In comparison with an alert, broadcast messages are created by an admin and not triggered by the
-system.
-
-Please refer to [Pajamas' documentation](https://design.gitlab.com/components/broadcast-message)
-for more information on when to use this component.
-
-## Dismiss a broadcast message
-
-The `GlBroadcastMessage` component deals with users dismissal the same way `GlAlert` does, meaning
-it does not handle its own visibility but emits a `dismiss` event that the parent component should
-listen to in order to hide the message. Example:
-
-```html
-<template>
-  ...
-  <gl-broadcast-message v-if="!dismissed" @dismiss="dismissed = true">
-    An important message
-  </gl-broadcast-message>
-  ...
-</template>
-```

package/src/components/base/button/button.md

@@ -1,119 +0,0 @@
-Buttons execute an action, either in the background or foreground of an experience. Different button
-categories help guide users through certain actions. Buttons express what action will occur when the
-user clicks or touches it either by text, icon, or both. Additional meaning can be derived from the
-button variant.
-
-## Button link
-
-A button link is a link that is styled to look like a button, semantically speaking it's a `<a>` tag
-with the necessary classes added to make it look like a button, it shares the same functionality as
-[<gl-link>](?path=/docs/base-link--docs)
-
-> Note: Setting a `target` attribute without a `href` attribute, will not create any side effects.
-> Without the presence of a `href` attribute, this component will render a `<button>`.
-
-## Icon-only button
-
-Icon-only buttons must have an accessible name.
-You can provide one with the `aria-label` attribute, which is read out by screen readers.
-
-```html
-<gl-button icon="close" aria-label="Close" />
-```
-
-## Type
-
-You can specify the button's type by setting the prop `type` to `button`, `submit` or `reset`.
-The default type is `button`.
-
-Note the `type` prop has no effect when either `href` or `to` props are set.
-
-## Sizing
-
-Specify `small` or `medium` via the `size` prop. Defaults to `medium`.
-
-```html
-<gl-button size="small">Small Button</gl-button>
-<gl-button>Default Button (medium)</gl-button>
-<gl-button size="medium">Medium Button</gl-button>
-```
-
-## Categories
-
-Use the `category` prop to set the button category to `primary`, `secondary`, or `tertiary`.
-Defaults to `primary`.
-
-## Variants
-
-Use the `variant` prop to set the button variant to `default`, `confirm`, `danger`, `dashed`, or `link`.
-Defaults to `default`.
-
-## Block level buttons
-
-Create block level buttons, those that span the full width of a parent, by setting the `block`
-prop.
-
-```html
-<gl-button block>Block Level Button</gl-button>
-```
-
-## Disabled state
-
-Set the `disabled` prop to disable button default functionality. `disabled` also works with buttons
-rendered as `<a>` elements and `<router-link>` (i.e. with the `href` or `to` prop set).
-
-```html
-<gl-button disabled>Disabled</gl-button>
-```
-
-## Router link support
-
-Refer to the [Router support](?path=/docs/base-link--docs#router-links) reference docs for
-the various supported `<router-link>` related props.
-
-## Accessibility
-
-When the `href` prop is set to `'#'`, `<gl-button>` will render a link (`<a>`) element with attribute
-`role="button"` set and appropriate keydown listeners (<kbd>Enter</kbd> and <kbd>Space</kbd>) so
-that the link acts like a native HTML `<button>` for screen reader and keyboard-only users. When
-disabled, the `aria-disabled="true"` attribute will be set on the `<a>` element.
-
-When the `href` is set to any other value (or the `to` prop is used), `role="button"` will not be
-added, nor will the keyboard event listeners be enabled.
-
-## Label button
-
-A label button renders a non-interactive `span` styled as a button. This can be especially useful
-when used in a button group to render text-only labels along with actionable buttons. To improve
-accessibility, and when applicable, consider using [`aria-describedby`] to establish a
-relationship between the label button and the associated button.
-
-[`aria-describedby`]: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques/Using_the_aria-describedby_attribute
-
-## 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-button
-  is-unsafe-link
-  download="file.txt"
-  href="data:text/plain;charset=utf-8,GitLab%20is%20awesome">Download</gl-button>
-```
-
-[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
-
-## vue-bootstrap component
-
-This component uses [`BButton`](https://bootstrap-vue.org/docs/components/button) from vue-bootstrap
-internally. So please take a look also there at their extensive documentation.

package/src/components/base/button_group/button_group.md

@@ -1,44 +0,0 @@
-Button groups are an easy way to group a series of buttons together.
-
-```html
-<gl-button-group>
-  <gl-button>Download</b-button>
-  <gl-button>Browse</b-button>
-  <gl-button variant="danger">Delete</b-button>
-</gl-button-group>
-```
-
-## Split dropdowns
-
-Both `GlCollapsibleListbox` and `GlDisclosureDropdown` can be added as the last
-child of a button group to produce a "split" dropdown.
-
-For the correct styling, the dropdown component must render a caret _only_.
-This means no icon, and no visible text. For accessbility, ensure the
-dropdown's `toggle-text` _and_ `text-sr-only` props are set.
-
-```html
-<gl-button-group>
-  <gl-button>Split listbox</gl-button>
-
-  <gl-collapsible-listbox
-    v-model="foo"
-    :items="items"
-    toggle-text="Choose button action"
-    text-sr-only
-  />
-</gl-button-group>
-```
-
-## Vertical variation
-
-Make a set of buttons appear vertically stacked rather than horizontally by setting the `vertical` prop.
-Split button dropdowns are not supported here.
-
-```html
-<gl-button-group vertical>
-  <gl-button>Top</b-button>
-  <gl-button>Middle</b-button>
-  <gl-button>Bottom</b-button>
-</gl-button-group>
-```

package/src/components/base/card/card.md

@@ -1,4 +0,0 @@
-Cards are a flexible component used to display content and actions in a variety of contexts.
-They are generally restricted to a single topic and it should be easy for users to scan relevant and
-actionable information. Content, such as images and text, should be positioned within them in a
-manner that demonstrates their intended hierarchy.

package/src/components/base/collapse/collapse.md

@@ -1,64 +0,0 @@
-Collapse is used to keep pages focused on the overview of what the user can do. Details and
-additional actions are hidden in the fold, and can be opened if the user wants to interact with
-those elements.
-
-## `v-model` support
-
-The component's collapsed (visible) state can be set with `v-model` which binds internally to
-the `visible` prop.
-
-Note that when using `v-model` to control `<gl-collapse>`, the `aria-*` attributes are not
-automatically placed on the trigger button. Specifically, you should add `aria-expanded` to
-reflect the state of the target `<gl-collapse>` component, and `aria-controls` should be set
-to the ID(s) of the target `<gl-collapse>` component(s).
-
-```html
-<template>
-  <div>
-    <gl-button
-      :class="visible ? null : 'collapsed'"
-      :aria-expanded="visible ? 'true' : 'false'"
-      aria-controls="collapse-4"
-      @click="visible = !visible"
-    >
-      Toggle Collapse
-    </gl-button>
-    <gl-collapse id="collapse-4" v-model="visible">
-      <span>Surprise! But I am just a span</span>
-    </gl-collapse>
-  </div>
-</template>
-
-<script>
-  export default {
-    data() {
-      return {
-        visible: true
-      }
-    }
-  }
-</script>
-```
-
-## Troubleshooting
-
-When collapsing the container, padding on the collapse component causes
-complications with the height calculations.
-The result is a bit of jumpiness at the end of the collapse animation.
-
-The quick solution is to bring the padding into an inner container, which
-simplifies the height calculations and removes the jumpiness.
-
-```html
-<!-- bad -->
-<gl-collapse class="gl-p-3">
-    <!-- content -->
-</gl-collapse>
-
-<!-- good -->
- <gl-collapse>
-    <div class="gl-p-3">
-        <!-- content -->
-    </div>
-</gl-collapse>
-```

package/src/components/base/datepicker/datepicker.md

@@ -1,8 +0,0 @@
-Date picker allows users to choose and input a date by manually typing the date into the input field
-or by using a calendar-like dropdown.
-
-### Warning
-
-Be careful when binding a date value using `value` prop. `value` is a watched property and Date
-picker will emit `input` event on _initial load_. Alternatively, use `defaultDate` to set the
-initial date then receive updated date values through `input` events.

package/src/components/base/daterange_picker/daterange_picker.md

@@ -1,32 +0,0 @@
-## Usage
-
-Daterange picker allows users to choose a date range by manually typing the start/end date
-into the input fields or by using a calendar-like dropdown.
-
-A `maxDateRange` can be specified in order to limit the maximum number of days the component
-will allow to be selected i.e. if the start date is `2020-08-01` and `maxDateRange` is set to `10`,
-the highest selectable end date would be `2020-08-11`. This value will be offset by `1` if
-`sameDaySelection` is set to `true`. A `defaultMaxDate` will need to be
-provided when making use of the `maxDateRange`.
-
-By default, the component does not allow selection of the same start and end date.
-In a scenario where this is required, the `sameDaySelection` property can be configured.
-This is specifically useful when a single day selection is being defined as `2020-01-01 00:00:00`
-to `2020-01-01 23:59:59` instead of `2020-01-01 00:00:00` to `2020-01-02 00:00:00`.
-
-When `maxDateRange` is set it's a good idea to set the `tooltip` specifying the date range limit
-and to indicate the number of days currently selected using the default slot. For example:
-
-```vue
-<template #default="{ daysSelected }">
-  <span v-if="daysSelected > -1">{{ daysSelected }} days selected</span>
-  <span v-else>No days selected</span>
-</template>
-```
-
-The `daysSelected` slot prop is the effective date range, thus the value is increased by one when
-`sameDaySelection` is set to `true`. When no date range has been selected the value is `-1`.
-
-### Note
-
-If specifying a maxDateRange, it is good practice to include a date range indicator and toolip.

package/src/components/base/drawer/drawer.md

@@ -1,17 +0,0 @@
-The drawer is used to show more information about a certain resource in the UI and potentially
-handle actions on the information.
-
-### By default
-
-```html
-<gl-drawer :open="open" @close="close" @opened="opened">
-  <template #header>Your Title</template>
-  <template>
-   ...children
-  </template>
-</gl-drawer>
-```
-
-- `v-bind:open` will be a boolean you will pass to `gl-drawer` and `@close` is a listener that will
-be a function that will toggle open to `false`.
-- The component emits an `opened` event after the opening animation has finished.

package/src/components/base/dropdown/dropdown.md

@@ -1,72 +0,0 @@
-The dropdown component offers a user multiple items or actions to choose from which are initially
-collapsed behind a button.
-
-> **NOTE**: This component has been deprecated in favor of components
-> more suited to the various use cases for dropdowns. Consider using a more
-> appropriate component instead:
->
-> - For single or multiselect options, use `GlCollapsibleListbox`.
-> - For displaying a list of actions like "Edit user", "Delete user", use `GlDisclosureDropdown`.
->
-> See [Which component should you use?](https://design.gitlab.com/components/dropdown-overview#which-component-should-you-use)
-> for what to use and when.
-
-### Icon-only dropdown
-
-Icon-only dropdowns must have an accessible name.
-You can provide this with the combination of `text` and `text-sr-only` props.
-
-Optionally, you can use `no-caret` to remove the caret and `category="tertiary"` to remove the border.
-
-```html
-<gl-dropdown
-  icon="ellipsis_v"
-  text="More actions"
-  :text-sr-only="true"
-  category="tertiary"
-  no-caret
->
-```
-
-### Button Content
-
-There are 3 ways to set the dropdown button's content.
-
-1. Use the `text` attribute. This will display the text with the loading spinner (shown with the
-`loading` attribute), icon (if provided by the `icon` attribute), and dropdown caret:
-
-    ```html
-    <gl-dropdown text="Button text">
-    ```
-
-1. Use the `button-text` template. This allows custom content for the button's text, but keeps the
-loading spinner, icon, and dropdown caret:
-
-    ```html
-    <gl-dropdown>
-      <template #button-text>
-        <!-- Loading spinner shown here -->
-        <!-- Icon shown here -->
-        Custom <strong>Content</strong> with <em>HTML</em> via Slot
-        <gl-truncate position="middle" text="Truncated button text"/>
-        <!-- Dropdown arrow shown here -->
-      </template>
-    </gl-dropdown>
-    ```
-
-1. Use the `button-content` template. This will replace everything in the button with the template:
-
-    ```html
-    <gl-dropdown>
-      <template #button-content>
-        Custom <strong>Content</strong> with <em>HTML</em> via Slot
-      </template>
-    </gl-dropdown>
-    ```
-
-### GlDropdownForm
-
-Unlike `b-dropdown-form`, we do _not_ add any additional padding with the `gl-dropdown-form` component.
-This is to prevent double padding with `gl-dropdown-item` and similar components, so in most cases
-shouldn't be needed. To add padding, either add a padding utility class to your form, or an inner
-element with some padding.

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

@@ -1,2 +0,0 @@
-The dropdown item component is meant to be used for clickable entries inside a dropdown component.
-If you provide the `href` attribute, it renders a link instead of a button.

package/src/components/base/dropdown/dropdown_section_header.md

@@ -1,7 +0,0 @@
-# Dropdown Section Header
-
-<!-- STORY -->
-
-## Usage
-
-The dropdown section header component is meant to be used for header entries inside a dropdown component.

package/src/components/base/dropdown/dropdown_text.md

@@ -1,7 +0,0 @@
-# Dropdown Text
-
-<!-- STORY -->
-
-## Usage
-
-The dropdown text component is meant to be used for text entries inside a dropdown component.

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.