@gitlab/ui 115.9.0 → 115.9.2

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.

package/src/components/base/progress_bar/progress_bar.md

@@ -1,25 +0,0 @@
-The progress bar component can be used to show an amount of progress.
-It comes in 4 variants and supports setting a custom maximum and height.
-
-## Value
-
-The `value` prop can be a Number or String. If not given, it will default to `0`.
-
-## Variants
-
-The following variants are available:
-
-1. 'primary' (default)
-2. 'success'
-3. 'warning'
-4. 'danger'
-
-## Maximum
-
-A custom maximum can be set with the `max` prop. If not given, it will default to `100`.
-
-## Width and Height
-
-The `GlProgressBar` will always expand to the maximum width of its parent container.
-The height can be controlled with the `height` prop. The value should be a standard
-CSS dimension (`px`, `rem`, `em`, etc.) and given as a String, e.g. `'20px'`.

package/src/components/base/search_box_by_click/search_box_by_click.md

@@ -1 +0,0 @@
-Provides a clearable text input with loading state to be used for [search](https://design.gitlab.com/components/search).

package/src/components/base/search_box_by_type/search_box_by_type.md

@@ -1 +0,0 @@
-Provides a clearable text input with loading state to be used for [search](https://design.gitlab.com/components/search).

package/src/components/base/segmented_control/segmented_control.md

@@ -1,26 +0,0 @@
-A customizable button group that displays a set of equal options, where only one
-option can be active at a time. This component includes the ability to disable
-specific options and dynamically modify button content using slots.
-
-## Features
-
-- Displays a group of selectable buttons.
-- Allows only one active selection at a time.
-- Supports content customization through the button-content slot.
-- Options can be disabled individually.
-
-## Props Validation
-
-The `options` prop is validated against a specific structure to ensure consistent
-data. Each option must include:
-
-- `value`: A `string`, `number`, or `boolean` to identify the option.
-- `disabled`: A `boolean` (or `undefined`) indicating whether the option is disabled.
-
-Optionally it can include:
-
-- `text`: A `string` which gets displayed in the slot content.
-
-## Notes
-
-- Ensure each value is unique within the options array for consistent behavior.

package/src/components/base/skeleton_loader/skeleton_loader.md

@@ -1,70 +0,0 @@
-Skeleton loaders are to be used when pages or sections can be progressively populated with content,
-such as text and images, as they become available. Generally speaking the first batch of content
-will be the lightest to load and is followed by secondary and tertiary content batches. Each loading
-step will add in more detail to the page until no skeleton loaders are present anymore. Content
-should replace skeleton objects immediately when the data is available.
-
-The skeleton loader component accepts shapes which in return will create a skeleton state with a
-loading animation. Any skeleton state components should be created with
-`<gl-skeleton-loader></gl-skeleton-loader>`. If no shape is passed via the slot the default skeleton
-will be used. See "Default" and "Default With Custom Props" examples.
-
-## The `.gl-animate-skeleton-loader` class
-
-Skeleton loaders can also be composed with a `.gl-animate-skeleton-loader`
-CSS class. This CSS-based approach is easier to make responsive and match mocked elements.
-Feel free to use this approach if it suits your use case and please leave your
-feedback in this [Feedback for css-based skeleton loading
-indicator](https://gitlab.com/gitlab-org/gitlab-ui/-/issues/2319) issue.
-To improve developer experience and simplify matching Pajamas styles we're considering
-several improvements in the future, including adding more CSS util classes for
-this animation, or creating a dedicated component.  Here is an example of how
-you could replicate the default `<gl-skeleton-loader />` behavior with the
-CSS-based approach:
-
-```html
-<div>
-  <div class="gl-animate-skeleton-loader gl-h-4 gl-rounded-base gl-my-3 !gl-max-w-20"></div>
-  <div class="gl-animate-skeleton-loader gl-h-4 gl-rounded-base gl-my-3 !gl-max-w-30"></div>
-  <div class="gl-animate-skeleton-loader gl-h-4 gl-rounded-base gl-my-3 !gl-max-w-26"></div>
-</div>
-```
-
-**USAGE NOTES:** if you're using `gl-max-w-xx` you'll need to add
-important (e.g. `!gl-max-w-20`). This is because `.gl-animate-skeleton-loader` already
-has a `max-width` statement, and we need to override it. You can override it
-only with lower numbers. Width rules (`gl-w-xx`) don't need an override, you
-can use them as-is. If you want to "synchronize" two elements next to each
-other, try adding `animation-delay` to offset elements.
-
-More complex example (with different shapes and an animation delay for offset elements):
-
-```html
-<div class="gl-display-flex gl-flex-direction-column gl-gap-2 gl-w-30">
-  <div class="gl-animate-skeleton-loader gl-h-8 gl-rounded-base gl-mb-4"></div>
-  <div class="gl-display-flex gl-flex-direction-row gl-gap-2">
-    <div class="gl-animate-skeleton-loader gl-h-8 gl-w-8 gl-rounded-full"></div>
-    <div class="gl-flex-grow-1" style="animation-delay: 100ms">
-      <div class="gl-animate-skeleton-loader gl-h-4 gl-rounded-base gl-my-2"></div>
-      <div class="gl-animate-skeleton-loader gl-h-4 gl-rounded-base gl-my-2"></div>
-      <div class="gl-animate-skeleton-loader gl-display-inline-block gl-h-4 gl-w-10 gl-rounded-base gl-my-2"></div>
-      <div
-        class="gl-animate-skeleton-loader gl-display-inline-block gl-h-4 gl-w-10 gl-rounded-base gl-my-2"
-        style="animation-delay: 250ms"></div>
-    </div>
-  </div>
-</div>
-```
-
-## Progressive Loading
-
-Determine if progressive loading is available, if it is break apart the skeleton to load data as it
-becomes readily available. If progessive loading is not available, replace the entire skeleton when
-the data is available.
-
-## Under the hood
-
-Skeleton Loader is a port of [vue-content-loader](https://github.com/egoist/vue-content-loader).
-Some changes have been made to the code to better suit our codebase, such as removing props and
-refactoring into a SFC. Please take a look at their documentation and a useful [UI tool](http://danilowoz.com/create-vue-content-loader/)
-for seeing the code output for `svg` shapes.

package/src/components/base/sorting/sorting.md

@@ -1,80 +0,0 @@
-The sorting component allows the user to select the field on which they would like to sort a list
-and whether to sort in ascending or descending order.
-
-Provide a list of sort options via the `sortOptions` prop with this structure:
-
-```typescript
-type sortOptionsProp = Array<{
-  value: string
-  text: string
-}>
-```
-
-The `value` should be a unique primitive value, and `text` is the user-facing
-string for that option.
-
-Set the currently selected sort option by passing a value to the `sortBy` prop.
-This should equal one of the `sortOptions` values. The selected sort option is
-rendered with a check mark next to it in the dropdown menu.
-
-When the user changes the selected sort option, a `sortByChange` event is
-emitted, with the `value` of the option as the only payload.
-
-The text of the dropdown trigger button is the `text` of the selected sort
-option. Pass a string to the `text` prop to override this behavior.
-
-When the user clicks on the sort direction button, a `sortDirectionChange`
-event is emitted, with a boolean value as its only payload. If the payload is
-`true`, the new order is ascending; otherwise it's descending.
-
-A complete implementation example might look like:
-
-```html
-<template>
-  <gl-sorting
-    :sort-options="sortOptions"
-    :sort-by="sortBy"
-    :is-ascending="isAscending"
-    @sortByChange="onSortByChange"
-    @sortDirectionChange="onDirectionChange"
-  />
-</template>
-
-<script>
-import { GlSorting } from '@gitlab/ui';
-
-export default {
-  components: {
-    GlSorting,
-  },
-  data() {
-    const sortOptions = [{
-      value: 'name',
-      text: 'Name',
-    }, {
-      value: 'date',
-      text: 'Date',
-    }];
-
-    return {
-      isAscending: false,
-      sortBy: sortOptions[0].value,
-      sortOptions,
-    }
-  },
-  methods: {
-    onSortByChange(value) {
-      this.sortBy = value;
-      this.sortMyData(this.sortBy, this.isAscending);
-    },
-    onDirectionChange(isAscending) {
-      this.isAscending = isAscending;
-      this.sortMyData(this.sortBy, this.isAscending);
-    },
-    sortMyData(sortBy, isAscending) {
-      // Use sortBy and direction to sort your data
-    },
-  }
-}
-</script>
-```

package/src/components/base/table/table.md

@@ -1,71 +0,0 @@
-## Usage
-
-The `gl-table` component wraps BootstrapVue `b-table` component. `b-table` provides a variety of
-slots for custom data rendering. You can learn more about them in the
-[component documentation](https://bootstrap-vue.org/docs/components/table).
-When using the component, pass in the `fields` prop as part of the `$options`, and give each table
-data and table head its own styles if necessary.
-
-## Internationalization
-
-To ensure we internationalize field labels, always pass an array of objects for the `fields` prop,
-like mentioned in the implementation example.
-
-[Learn more about the `field` prop](https://gitlab.com/gitlab-org/gitlab-services/design.gitlab.com/-/blob/2e88af62966265cb725ca3f65f4b175e2494734b/packages/gitlab-ui/src/vendor/bootstrap-vue/src/components/table/README.md#L137).
-
-## Header text alignment
-
-To align a given `TH` element's text to the right, set the `thAlignRight` property to `true` in
-the fields definition. This will ensure that proper styling is applied, including when the column
-is sortable.
-
-```js
-const fields = [
-  {
-    key: "column_one",
-    label: __("First column"),
-    sortable: true,
-    thAlignRight: true,
-  },
-];
-```
-
-## Use `GlTableLite` when possible
-
-If you don't need all the features of `GlTable`, like filtering, sorting, or
-pagination, use `GlTableLite` which offers a subset of `GlTable` features.
-
-## Implementation Example
-
-```html
-<script>
-  export default {
-    fields: [
-      {
-        key: 'column_one',
-        label: __('First column'),
-        thClass: 'w-60p',
-        tdClass: 'table-col d-flex'
-      },
-      {
-        key: 'col_2',
-        label: __('Second column'),
-        thClass: 'w-15p',
-        tdClass: 'table-col d-flex'
-      },
-    ];
-  }
-</script>
-<template>
-  <gl-table :items="items" :fields="$options.fields">
-    <template #head(column_one)>
-      <div>First column</div>
-      <!-- This is the column head for the first object in `fields` -->
-    </template>
-
-    <template #cell(column_one)>
-      This is the template for column data belonging to the first object
-    </template>
-  </gl-table>
-</template>
-```

package/src/components/base/table_lite/table_lite.md

@@ -1,68 +0,0 @@
-## Usage
-
-The `GlTableLite` component wraps BootstrapVue `BTableLite` component.
-`BTableLite` provides a variety of slots for custom data rendering. You can learn
-more about them in the
-[component documentation](https://bootstrap-vue.org/docs/components/table#light-weight-tables).
-
-## `GlTable` vs. `GlTableLite`
-
-`GlTableLite` adds less payload to the pagebundle than `GlTable`.
-When possible `GlTableLite` should be preferred over `GlTable`.
-
-The `GlTableLite` component provides all of the styling and formatting features of
-`GlTable` (including row details and stacked support), while excluding the following features:
-
-- Filtering
-- Sorting
-- Pagination
-- Items provider support
-- Selectable rows
-- Busy table state and styling
-- Fixed top and bottom rows
-- Empty row support
-
-## Internationalization
-
-To ensure we internationalize field labels, always pass an array of objects for the `fields` prop,
-like mentioned in the implementation example.
-
-[Learn more about the `field` prop](https://gitlab.com/gitlab-org/gitlab-services/design.gitlab.com/-/blob/2e88af62966265cb725ca3f65f4b175e2494734b/packages/gitlab-ui/src/vendor/bootstrap-vue/src/components/table/README.md#L137).
-
-## Implementation example
-
-```html
-<script>
-export default {
-  fields: [
-    {
-      key: 'column_one',
-      label: __('First column'),
-      thClass: 'w-60p',
-      tdClass: 'table-col d-flex'
-    },
-    {
-      key: 'col_2',
-      label: __('Second column'),
-      thClass: 'w-15p',
-      tdClass: 'table-col d-flex'
-    },
-  ];
-}
-</script>
-<template>
-  <gl-table-lite
-    :items="items"
-    :fields="$options.fields"
-  >
-    <template #head(column_one)>
-      <div>First column</div><!-- This is the column head for the first object in `fields` -->
-    </template>
-
-    <template #cell(column_one)>
-      This is the template for column data belonging to the first object
-    </template>
-
-  </gl-table-lite>
-</template>
-```