@gitlab/ui 115.11.0 → 117.0.0

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

@@ -1,52 +0,0 @@
-Use this component to add a [`FormInput`](/?path=/story/base-form-form-input--default) component
-with synchronous autocomplete dropdown. It behaves as follows:
-
-- Typing matches tokens; dropdown disappears when there is no match  
-- Up and down arrows navigate the dropdown  
-- Enter selects keyboard-highlighted item; clicking overrides this  
-- Esc closes dropdown when it is open, clears field when it is not  
-- Browser/native autocomplete dropdown hidden when ours is open, shows when it is not  
-- Tab selects current entered text and moves to next field  
-
-This behavior based on
-[this w3c pattern](https://www.w3.org/TR/wai-aria-practices/examples/combobox/aria1.1pattern/listbox-combo.html)
-and [this accessible combobox example](https://alligator.io/vuejs/vue-a11y-autocomplete/).
-
-## Usage
-
-The combobox accepts an array of string tokens, a `v-model`, and label text. Internally, it generates
-unique element IDs so multiple can be used on one page without clashing.
-
-On selection it sets the input value to the selected string and emits a `value-selected` event for
-consumption by parent components.
-
-```html
-<gl-form-combobox
-  v-model="inputVal"
-  :token-list="tokens"
-  label-text="Combobox Label"
-/>
-```
-
-It does not have a loading state nor does it accept tokens other than strings. It allows for one
-selected value.
-
-### What if I need to load the options asynchronously?
-
-You may want to look at [`GlSearchBoxByType`] or [`GlSearchBoxByClick`].
-
-### What if I need multiple options?
-
-The [`GlTokenSelector`] may be what you need. Alternately, [`GlFilteredSearch`] will let you search
-and include tokens.
-
-## Edge cases
-
-The algorithm to match tokens with the input is very naive. If you need to use the component with a
-very large list of matches, you may want to update the implementation or use one of the search
-inputs, like [`GlSearchBoxByType`], [`GlSearchBoxByClick`], or [`GlFilteredSearch`].
-
-[`GlSearchBoxByType`]: https://design.gitlab.com/storybook?path=/story/base-search-box-by-type--default
-[`GlSearchBoxByClick`]: https://design.gitlab.com/storybook?path=/story/base-search-box-by-click--default
-[`GlTokenSelector`]: https://design.gitlab.com/storybook?path=/story/base-token-selector--default
-[`GlFilteredSearch`]: https://design.gitlab.com/storybook?path=/story/base-filtered-search--default

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

@@ -1,26 +0,0 @@
-`GlFormDate` allows users to choose and input a date using a keyboard by by using
-browser implemented calendar controls, where available.
-
-`GlFormDate` extends `<input type="date">` with an `<output>` for audible announcement
-of selected date, in full format, by screen-readers.
-
-## Usage
-
-On `change` the value is emitted in `YYYY-MM-DD` format.
-
-## Accessibility
-
-`GlFormDate` is a form `<input>` and should have an accessible name using a `<label>`.
-
-`GlFormGroup` can be used to label `GlFormDate`.
-
-```html
-<gl-form-group
-  label="Enter date"
-  label-for="input-id"
->
-  <gl-form-date
-    id="input-id"
-  />
-</gl-form-group>
-```

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

@@ -1,41 +0,0 @@
-## Usage
-
-`GlFormFields` provides form builder functionality for ease of building simple
-forms out of other GitLab UI form components.
-
-For a code example, look at the story. It covers usage of `mapValue`, `validators`,
-custom form elements, and `inputAttrs`.
-
-## Fields type
-
-Each value of `fields` prop is expected to be a `FieldDefinition`. See below for the shape of this type:
-
-```ts
-interface FieldDefinition<TValue> {
-  // Label text to show for this field.
-  label: string;
-
-  // Collection of validator functions
-  validators?: Array<(value: TValue) => string | undefined>;
-
-  // Function that maps the inputted string value to the field's actual value
-  // (e.g. a Number).
-  mapValue?: (input: string) => TValue;
-
-  // Properties that are passed to the actual input for this field.
-  inputAttrs?: {};
-
-  // Properties that are passed to the group wrapping this field.
-  groupAttrs?: {};
-}
-```
-
-## Slots
-
-| Name | Description |
-| ------ | ------ |
-| `input(<fieldName>)` | Used to render components other than `GlFormInput`. |
-| `group(<fieldName>)-label` | Used for `label` slot on `GlFormGroup` of a specific field. |
-| `group(<fieldName>)-description` | Used for `description` slot on `GlFormGroup` of a specific field. |
-| `group(<fieldName>)-label-description` | Used for `label-description` slot on `GlFormGroup` of a specific field. |
-| `after(<fieldName>)` | Used to render content after `GlFormGroup` of a specific field. |

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

@@ -1 +0,0 @@
-Form group adds structure to forms.

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

@@ -1,67 +0,0 @@
-The `GlFormInputGroup` component allows one to build more advanced text
-input fields than generic `GlFormInput` when one needs that flexibility.
-Basic usage of the component:
-
-```html
-<div>
-  <gl-form-input-group>
-    <template #prepend>
-      <!-- Content to prepend your text input field -->
-    </template>
-    <template #append>
-      <!-- Content to append your text input field -->
-    </template>
-  </gl-form-input-group>
-</div>
-```
-
-One can use any other component (custom or `<gl-*>`) in both slots or
-not to use the slots at all. In the latter, the component will fallback
-to simple `GlFormInput`.
-
-## Predefined options
-
-Sometimes custom text input from the user isn't desired. Instead, the
-user should pick one of the predefined options that will automatically
-populate the input field. Typically, such cases will also include an
-actionable button (like **Copy**) put into the `append` slot.
-
-To achieve this effect, the `GlFormInputGroup` component accepts an
-array of options in the form of `predefinedOptions` param. For example:
-
-```javascript
-const optionValues = [
-  { name: 'Option #1', value: 'Option #1 is selected!' },
-  { name: 'Option #2', value: 'Option #2 is selected!' },
-];
-...
-<gl-form-input-group :predefined-options="optionValues" />
-```
-
-This will tell `GlFormInputGroup` to render a dropdown in the `prepend`
-slot with all of the supplied options' `name`s. When one of the options
-is selected, the input field is automatically populated with the
-option's `value`. Check the "Examples" section below for "With
-predefined options" example.
-
-### Pro tips
-
-Read some useful tips below about specific usage of the component.
-
-### Readonly input
-
-Often you want to make sure user doesn't mess up the predefined content
-pasted into the input field. In this case, you can set `readonly`
-param to `true`. You can play with `Readonly` knob on the right.
-
-### Preselect the text to copy
-
-If you set the `readonly` param on the `GlFormInputGroup` component,
-users will still be able to manually select the text and copy it.
-However, it's more user-friendly to preselect the text for the users if
-they click anywhere in the input field. This can be achieved by setting
-the `select-on-click` param to `true`. You can play with
-`Select text on click` knob on the right. Even better, try enabling
-`Readonly`, `Select text on click`, and `Switch to predefined input`
-altogether. And, probably, remove `Prepend text`. Or leave it. It's your
-call. :)

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

@@ -1 +0,0 @@
-GlInputGroupText components are used to add text to an input group.

package/src/components/base/nav/nav.md

@@ -1,184 +0,0 @@
-## Overview
-
-The base `<gl-nav>` component is built with flexbox and provides a strong foundation for building all
-types of navigation components. It includes some style overrides (for working with lists), some link
-padding for larger hit areas, and basic disabled styling. No active states are included in the base
-nav.
-
-`<gl-nav>` supports the `<gl-nav-item>` child component for actionable links (or router-links).
-
-## Link appearance
-
-Two style variations are supported: `tabs` and `pills`, which support `active` state styling. These
-variants are mutually exclusive - use only one style or the other.
-
-### Tab style
-
-Make the nav look like tabs by setting the `tabs` prop.
-
-```html
-<div>
-  <gl-nav tabs>
-    <gl-nav-item active>Active</gl-nav-item>
-    <gl-nav-item>Link</gl-nav-item>
-    <gl-nav-item>Another Link</gl-nav-item>
-    <gl-nav-item disabled>Disabled</gl-nav-item>
-  </gl-nav>
-</div>
-```
-
-### Pill style
-
-Use the pill style by setting the `pills` prop.
-
-```html
-<div>
-  <gl-nav pills>
-    <gl-nav-item active>Active</gl-nav-item>
-    <gl-nav-item>Link</gl-nav-item>
-    <gl-nav-item>Another Link</gl-nav-item>
-    <gl-nav-item disabled>Disabled</gl-nav-item>
-  </gl-nav>
-</div>
-```
-
-### Small
-
-Make the nav smaller by setting the `small` prop.
-
-```html
-<div>
-  <gl-nav small>
-    <gl-nav-item active>Active</gl-nav-item>
-    <gl-nav-item>Link</gl-nav-item>
-    <gl-nav-item>Another Link</gl-nav-item>
-    <gl-nav-item disabled>Disabled</gl-nav-item>
-  </gl-nav>
-</div>
-```
-
-## Fill and justify
-
-Force your `<gl-nav>` content to extend the full available width.
-
-### Fill
-
-To proportionately fill all available space with your `<gl-nav-item>` components, set the `fill`
-prop. Notice that all horizontal space is occupied, but not every nav item has the same width.
-
-```html
-<div>
-  <gl-nav tabs fill>
-    <gl-nav-item active>Active</gl-nav-item>
-    <gl-nav-item>Link</gl-nav-item>
-    <gl-nav-item>Link with a long name </gl-nav-item>
-    <gl-nav-item disabled>Disabled</gl-nav-item>
-  </gl-nav>
-</div>
-```
-
-### Justified
-
-For equal-width elements, set the `justified` prop instead. All horizontal space will be occupied by
-nav links, but unlike `fill` above, every `<gl-nav-item>` will be the same width.
-
-```html
-<div>
-  <gl-nav tabs justified>
-    <gl-nav-item active>Active</gl-nav-item>
-    <gl-nav-item>Link</gl-nav-item>
-    <gl-nav-item>Link with a long name </gl-nav-item>
-    <gl-nav-item disabled>Disabled</gl-nav-item>
-  </gl-nav>
-</div>
-```
-
-## Alignment
-
-To align your `<gl-nav-item>` components, use the `align` prop. Available values are `left`, `center`
-and `right`.
-
-```html
-<div>
-  <gl-nav tabs align="center">
-    <gl-nav-item active>Active</gl-nav-item>
-    <gl-nav-item>Link</gl-nav-item>
-    <gl-nav-item>Link with a long name </gl-nav-item>
-    <gl-nav-item disabled>Disabled</gl-nav-item>
-  </gl-nav>
-</div>
-```
-
-## Tabbed local content support
-
-See the [`<gl-tabs>`](?path=/docs/base-tabs--docs) component for creating tabbable panes of local
-content (not suited for navigation).
-
-## Card integration
-
-Use a `<gl-nav>` in a [`<gl-card>`](?path=/docs/base-card--docs) header, by enabling the
-`card-header` prop on `<gl-nav>` and setting either the `pills` or `tabs` props:
-
-```html
-<div>
-  <gl-card title="Card Title">
-    <template #header>
-      <gl-nav card-header tabs>
-        <gl-nav-item active>Active</gl-nav-item>
-        <gl-nav-item>Inactive</gl-nav-item>
-      </gl-nav>
-    </template>
-
-    <template #default>
-      <p>With supporting text below as a natural lead-in to additional content.</p>
-      <gl-button variant="primary">Go somewhere</gl-button>
-    </template>
-  </gl-card>
-</div>
-```
-
-**Plain style:**
-
-The `card-header` prop is only needed when you are applying `tabs` or `pills` style. Note that
-we do not have special styling for `active` state plain style nav items.
-
-```html
-<div>
-  <gl-card title="Card Title">
-    <template #header>
-      <gl-nav>
-        <gl-nav-item active>Active</gl-nav-item>
-        <gl-nav-item>Inactive</gl-nav-item>
-      </gl-nav>
-    </template>
-
-    <template #default>
-      <p>pWith supporting text below as a natural lead-in to additional content.</p>
-      <gl-button variant="primary">Go somewhere</gl-button>
-    </template>
-  </gl-card>
-</div>
-```
-
-## Accessibility
-
-If you're using `<gl-nav>` to provide a navigation bar, be sure to add a `role="navigation"` to the
-most logical parent container of `<gl-nav>`, or wrap a `<nav>` element around `<gl-nav>`. Do **not**
-add the role to the `<gl-nav>` itself, as this would prevent it from being announced as an actual
-list by assistive technologies.
-
-### Tabbed interface accessibility
-
-Note that navigation bars, even if visually styled as tabs, should **not** be given
-`role="tablist"`, `role="tab"` or `role="tabpanel"` attributes. These are only appropriate for
-[tabbed interfaces](?path=/docs/base-tabs--docs) that do not change the URL or `$route`, as
-described in the [WAI ARIA Authoring Practices](https://www.w3.org/TR/wai-aria-practices/#tabpanel).
-See [`<gl-tabs>`](?path=/docs/base-tabs--docs) for dynamic tabbed interfaces that are compliant with
-WAI ARIA.
-
-## See also
-
-- [tabs](?path=/docs/base-tabs--docs) to create tabbable panes of local content, even via dropdown
-  menus.
-- [Router Link Support reference](?path=/docs/base-link--docs#router-link-support) for information
-  about router-link specific props available on `<gl-nav-item>`

package/src/components/base/nav/nav.scss

@@ -1,7 +0,0 @@
-.nav {
-  &-link {
-    &:focus-visible {
-      @apply gl-focus;
-    }
-  }
-}

package/src/components/base/nav/nav.vue

@@ -1,70 +0,0 @@
-<script>
-export default {
-  name: 'GlNav',
-  props: {
-    /**
-     * Align the nav items in the nav: 'start' (or 'left'), 'center', 'end' (or 'right')
-     */
-    align: { type: String, required: false, default: '' },
-    /**
-     * Set this prop when the nav is placed inside a card header
-     */
-    cardHeader: { type: Boolean, required: false, default: false },
-    /**
-     * Proportionately fills all horizontal space with nav items.
-     * All horizontal space is occupied, but not every nav item has the same width
-     */
-    fill: { type: Boolean, required: false, default: false },
-    /**
-     * Fills all horizontal space with nav items, but unlike 'fill', every nav item will be the same width
-     */
-    justified: { type: Boolean, required: false, default: false },
-    /**
-     * Renders the nav items with the appearance of pill buttons
-     */
-    pills: { type: Boolean, required: false, default: false },
-    /**
-     * Makes the nav smaller
-     */
-    small: { type: Boolean, required: false, default: false },
-    /**
-     * Renders the nav items with the appearance of tabs
-     */
-    tabs: { type: Boolean, required: false, default: false },
-    /**
-     * Specify the HTML tag to render instead of the default tag
-     */
-    tag: { type: String, required: false, default: 'ul' },
-  },
-  computed: {
-    justifyContent() {
-      if (!this.align) return '';
-
-      const alignMapping = {
-        left: 'start',
-        right: 'end',
-      };
-
-      return `justify-content-${alignMapping[this.align] || this.align}`;
-    },
-    classes() {
-      return {
-        'nav-tabs': this.tabs,
-        'nav-pills': this.pills && !this.tabs,
-        'card-header-tabs': this.cardHeader && this.tabs,
-        'card-header-pills': this.cardHeader && this.pills && !this.tabs,
-        'nav-fill': this.fill,
-        'nav-justified': this.justified,
-        [this.justifyContent]: this.align,
-        small: this.small,
-      };
-    },
-  },
-};
-</script>
-
-<template>
-  <component :is="tag" class="nav" :class="classes" v-on="$listeners">
-    <slot></slot>
-  </component>
-</template>

package/src/components/base/nav/nav_item.vue

@@ -1,109 +0,0 @@
-<script>
-import GlLink from '../link/link.vue';
-
-export default {
-  name: 'GlNavItem',
-  components: {
-    GlLink,
-  },
-  props: {
-    /**
-     * When set to `true`, places the component in the active state with active styling
-     */
-    active: {
-      type: Boolean,
-      required: false,
-      default: false,
-    },
-    /**
-     * When set to `true`, disables the component's functionality and places it in a disabled state.
-     */
-    disabled: {
-      type: Boolean,
-      required: false,
-      default: false,
-    },
-    /**
-     * Denotes the target URL of the link for standard links.
-     */
-    href: {
-      type: String,
-      required: false,
-      default: undefined,
-    },
-    /**
-     * <router-link> prop: 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.
-     */
-    to: {
-      type: [Object, String],
-      required: false,
-      default: undefined,
-    },
-    /**
-     * <router-link> prop: Configure the active CSS class applied when the link is active.
-     */
-    activeClass: {
-      type: String,
-      required: false,
-      default: undefined,
-    },
-    /**
-     * <router-link> prop: Configure the active CSS class applied when the link is active with exact match.
-     */
-    exactActiveClass: {
-      type: String,
-      required: false,
-      default: undefined,
-    },
-    /**
-     * Attributes for the link element
-     */
-    linkAttrs: {
-      type: Object,
-      required: false,
-      default: null,
-    },
-    /**
-     * Classes for the link element
-     */
-    linkClasses: {
-      type: Array,
-      required: false,
-      default: () => [],
-    },
-  },
-  computed: {
-    computedLinkClasses() {
-      const classes = this.linkClasses;
-
-      // the `unstyled` link variant does not do this by itself
-      if (this.disabled) classes.push('disabled');
-      if (this.active) classes.push('active');
-
-      return classes;
-    },
-  },
-};
-</script>
-
-<template>
-  <li class="nav-item">
-    <gl-link
-      class="nav-link"
-      variant="unstyled"
-      :active="active"
-      :class="computedLinkClasses"
-      :disabled="disabled"
-      :href="href"
-      :to="to"
-      :active-class="activeClass"
-      :exact-active-class="exactActiveClass"
-      v-bind="linkAttrs"
-      v-on="$listeners"
-    >
-      <slot></slot>
-    </gl-link>
-  </li>
-</template>

package/src/components/base/token_selector/token_selector.md

@@ -1,78 +0,0 @@
-Choose from a provided list of tokens or add a user defined token.
-
-```html
-<script>
-export default {
-  data() {
-    return {
-      selectedTokens: [
-        {
-          id: 1,
-          name: 'Vue.js',
-        },
-      ],
-    };
-  },
-};
-</script>
-
-<template>
-  <div>
-    <gl-token-selector
-      v-model="selectedTokens"
-      :dropdown-items="[
-        {
-          id: 1,
-          name: 'Vue.js',
-        },
-        {
-          id: 2,
-          name: 'Ruby On Rails',
-        },
-        {
-          id: 3,
-          name: 'GraphQL',
-        },
-        {
-          id: 4,
-          name: 'Redis',
-        },
-      ]"
-    />
-    {{ selectedTokens }}
-  </div>
-</template>
-```
-
-## User created tokens
-
-This component allows for users to create their own tokens when configured to do so.
-There are two props that support this functionality: `allowUserDefinedTokens` and `showAddNewAlways`.
-
-`allowUserDefinedTokens` is required to enable the functionality
-
-When set to `true` and a user's search text returns nothing,
-they will be presented with an additional dropdown item `Add ...`
-that takes their current search input and emits `@input`.
-The parent component can then handle the event accordingly.
-
-Additionally, there are scenarios where the user may want the ability to add a new token
-even if some search results are returned.  This functionality can be enabled by additionally
-setting `showAddNewAlways` to `true`.
-This will allow for the `Add ...` dropdown item to appear at all times
-whenever a user has inputted text, regardless if results are found.
-
-```html
-<template>
-  <div>
-    <gl-token-selector
-      v-model="selectedTokens"
-      :dropdown-items="dropdownItems"
-      allow-user-defined-items
-      show-ad-new-always
-      @input="onTokenUpdate"
-    />
-    {{ selectedTokens }}
-  </div>
-</template>
-```

package/src/components/charts/bar/bar.md

@@ -1,3 +0,0 @@
-A bar chart is similar to a column chart where the the length of bars represents the data value.
-Although alike, they are cannot be interchangeably used. Bar charts are good for displaying large
-number of categories on the y-axis.

package/src/components/charts/chart/chart.md

@@ -1,19 +0,0 @@
-### ECharts Wrapper
-
-The chart component is a Vue component wrapper around [Apache ECharts](https://echarts.apache.org/en/api.html#echarts).
-The chart component accepts width and height props in order to allow the user to make it responsive.
-
-> Note: When implementing a chart type that does not already have a GitLab UI component, you can use
-> this component alonside the [ECharts options](https://echarts.apache.org/en/api.html#echarts) to
-> build your chart. Each type of chart should still follow the general guidelines in the
-> [pajamas documentation](https://design.gitlab.com/data-visualization/charts).
-
-### EChart Lifecycle
-
-This component emits the following events during the ECharts lifecycle:
-
-- `created`: emitted after calling `echarts.init`
-- `updated`: emitted after calling `echarts.setOption`
-
-In all cases, the event payload is the
-[echart instance](https://echarts.apache.org/en/api.html#echartsInstance).

package/src/components/charts/gauge/gauge.md

@@ -1,8 +0,0 @@
-Some layout problems can be encountered with this component. Specifically, when the gauge chart's
-axis labels or detail text have larger widths, they can overlap with the chart elements.
-
-Also, when the containing element of the gauge chart has either of a small calculated `width` and
-`height`, its axis width could become bulkier in relation to other chart elements. This is because
-at this time [eCharts only allows for setting the axis line width in absolute units](https://echarts.apache.org/en/option.html#series-gauge.axisLine.lineStyle.width).
-
-This issue is to be addressed by [https://gitlab.com/gitlab-org/gitlab-ui/-/issues/916](https://gitlab.com/gitlab-org/gitlab-ui/-/issues/916).

package/src/components/charts/heatmap/heatmap.md

@@ -1,7 +0,0 @@
-## Heatmaps
-
-**Note** This component uses `<gl-legend>`, which should allow a user to click on any data point(s)
-in the legend and make the corresponding data point(s) on the chart rendered disappear.
-_See [area chart](https://design.gitlab.com/storybook?path=/story/charts-area-chart--default)
-for an example_ For this particular chart, there is a [known issue](https://gitlab.com/gitlab-org/gitlab-ui/issues/352)
-with the functionality of the legend, where clicking on it does nothing.