@gitlab/ui 114.1.0 → 114.1.2

package/src/vendor/bootstrap-vue/src/components/form-checkbox/README.md

@@ -1,691 +0,0 @@
-# Form Checkbox
-
-> For cross browser consistency, `<b-form-checkbox-group>` and `<b-form-checkbox>` use Bootstrap's
-> custom checkbox input to replace the browser default checkbox input. It is built on top of
-> semantic and accessible markup, so it is a solid replacement for the default checkbox input.
-
-**Example 1:** Single checkbox
-
-```html
-<template>
-  <div>
-    <b-form-checkbox
-      id="checkbox-1"
-      v-model="status"
-      name="checkbox-1"
-      value="accepted"
-      unchecked-value="not_accepted"
-    >
-      I accept the terms and use
-    </b-form-checkbox>
-
-    <div>State: <strong>{{ status }}</strong></div>
-  </div>
-</template>
-
-<script>
-  export default {
-    data() {
-      return {
-        status: 'not_accepted'
-      }
-    }
-  }
-</script>
-
-<!-- b-form-checkbox.vue -->
-```
-
-**Example 2:** Multiple choice checkboxes
-
-```html
-<template>
-  <div>
-    <b-form-group label="Using options array:" v-slot="{ ariaDescribedby }">
-      <b-form-checkbox-group
-        id="checkbox-group-1"
-        v-model="selected"
-        :options="options"
-        :aria-describedby="ariaDescribedby"
-        name="flavour-1"
-      ></b-form-checkbox-group>
-    </b-form-group>
-
-    <b-form-group label="Using sub-components:" v-slot="{ ariaDescribedby }">
-      <b-form-checkbox-group
-        id="checkbox-group-2"
-        v-model="selected"
-        :aria-describedby="ariaDescribedby"
-        name="flavour-2"
-      >
-        <b-form-checkbox value="orange">Orange</b-form-checkbox>
-        <b-form-checkbox value="apple">Apple</b-form-checkbox>
-        <b-form-checkbox value="pineapple">Pineapple</b-form-checkbox>
-        <b-form-checkbox value="grape">Grape</b-form-checkbox>
-      </b-form-checkbox-group>
-    </b-form-group>
-
-    <div>Selected: <strong>{{ selected }}</strong></div>
-  </div>
-</template>
-
-<script>
-  export default {
-    data() {
-      return {
-        selected: [], // Must be an array reference!
-        options: [
-          { text: 'Orange', value: 'orange' },
-          { text: 'Apple', value: 'apple' },
-          { text: 'Pineapple', value: 'pineapple' },
-          { text: 'Grape', value: 'grape' }
-        ]
-      }
-    }
-  }
-</script>
-
-<!-- b-form-checkbox-multiple.vue -->
-```
-
-Feel free to mix and match `options` prop and `<b-form-checkbox>` in `<b-form-checkbox-group>`.
-Manually placed `<b-form-checkbox>` inputs will appear _below_ any checkbox inputs generated by the
-`options` prop. To have them appear _above_ the inputs generated by `options`, place them in the
-named slot `first`.
-
-## Checkbox group options array
-
-`options` can be an array of strings or objects. Available fields:
-
-- **`value`** The selected value which will be set on `v-model`
-- **`disabled`** Disables item for selection
-- **`text`** Display text, or **`html`** Display basic inline html
-
-`value` can be a string, number, or simple object. Avoid using complex types in values.
-
-If both `html` and `text` are provided, `html` will take precedence. Only basic/native HTML is
-supported in the `html` field (components will not work). Note that not all browsers will render
-inline html (i.e. `<i>`, `<strong>`, etc.) inside `<option>` elements of a `<select>`.
-
-<p class="alert alert-danger">
-  <strong>Be cautious</strong> of placing user supplied content in the <code>html</code> field,
-  as it may make you vulnerable to
-  <a class="alert-link" href="https://en.wikipedia.org/wiki/Cross-site_scripting">
-  <abbr title="Cross Site Scripting Attacks">XSS attacks</abbr></a>, if you do not first
-  <a class="alert-link" href="https://en.wikipedia.org/wiki/HTML_sanitization">sanitize</a> the
-  user supplied string.
-</p>
-
-<!-- eslint-disable no-unused-vars -->
-
-```js
-const options = ['A', 'B', 'C', { text: 'D', value: { d: 1 }, disabled: true }, 'E', 'F']
-```
-
-If an array entry is a string, it will be used for both the generated `value` and `text` fields.
-
-You can mix using strings and [objects](#options-as-an-array-of-objects) in the array.
-
-Internally, BootstrapVue will convert the above array to the following array (the
-[array of objects](#options-as-an-array-of-objects)) format:
-
-<!-- eslint-disable no-unused-vars -->
-
-```js
-const options = [
-  { text: 'A', value: 'A', disabled: false },
-  { text: 'B', value: 'B', disabled: false },
-  { text: 'C', value: 'C', disabled: false },
-  { text: 'D', value: { d: 1 }, disabled: true },
-  { text: 'E', value: 'E', disabled: false },
-  { text: 'F', value: 'F', disabled: false }
-]
-```
-
-### Options as an array of objects
-
-<!-- eslint-disable no-unused-vars -->
-
-```js
-const options = [
-  { text: 'Item 1', value: 'first' },
-  { text: 'Item 2', value: 'second' },
-  { html: '<b>Item</b> 3', value: 'third', disabled: true },
-  { text: 'Item 4' },
-  { text: 'Item 5', value: { foo: 'bar', baz: true } }
-]
-```
-
-If `value` is missing, then `text` will be used as both the `value` and `text` fields. If you use
-the `html` property, you **must** supply a `value` property.
-
-Internally, BootstrapVue will convert the above array to the following array (the
-[array of objects](#options-as-an-array-of-objects)) format:
-
-<!-- eslint-disable no-unused-vars -->
-
-```js
-const options = [
-  { text: 'Item 1', value: 'first', disabled: false },
-  { text: 'Item 2', value: 'second', disabled: false },
-  { html: '<b>Item</b> 3', value: 'third', disabled: true },
-  { text: 'Item 4', value: 'Item 4', disabled: false },
-  { text: 'Item 5', value: 'E', disabled: false }
-]
-```
-
-### Changing the option field names
-
-If you want to customize the field property names (for example using `name` field for display
-`text`) you can easily change them by setting the `text-field`, `html-field`, `value-field`, and
-`disabled-field` props to a string that contains the property name you would like to use:
-
-```html
-<template>
-  <div>
-    <b-form-checkbox-group
-      v-model="selected"
-      :options="options"
-      class="mb-3"
-      value-field="item"
-      text-field="name"
-      disabled-field="notEnabled"
-    ></b-form-checkbox-group>
-    <div class="mt-3">Selected: <strong>{{ selected }}</strong></div>
-  </div>
-</template>
-
-<script>
-  export default {
-    data() {
-      return {
-        selected: [],
-        options: [
-          { item: 'A', name: 'Option A' },
-          { item: 'B', name: 'Option B' },
-          { item: 'D', name: 'Option C', notEnabled: true },
-          { item: { d: 1 }, name: 'Option D' }
-        ]
-      }
-    }
-  }
-</script>
-
-<!-- b-form-checkbox-group-options-fields.vue -->
-```
-
-## Inline and stacked checkboxes
-
-`<b-form-checkbox-group>` components render inline checkboxes by default, while `<b-form-checkbox>`
-renders block-level (stacked) checkboxes.
-
-Set the prop `stacked` on `<b-form-checkbox-group>` to place each form control one over the other,
-or if using individual checkboxes not inside a `<b-form-checkbox-group>`, set the `inline` prop on
-`<b-form-checkbox>`.
-
-```html
-<template>
-  <div>
-    <b-form-group
-      label="Form-checkbox-group inline checkboxes (default)"
-      v-slot="{ ariaDescribedby }"
-    >
-      <b-form-checkbox-group
-        v-model="selected"
-        :options="options"
-        :aria-describedby="ariaDescribedby"
-        name="flavour-1a"
-      ></b-form-checkbox-group>
-    </b-form-group>
-
-    <b-form-group
-      label="Form-checkbox-group stacked checkboxes"
-      v-slot="{ ariaDescribedby }"
-    >
-      <b-form-checkbox-group
-        v-model="selected"
-        :options="options"
-        :aria-describedby="ariaDescribedby"
-        name="flavour-2a"
-        stacked
-      ></b-form-checkbox-group>
-    </b-form-group>
-
-    <b-form-group
-      label="Individual stacked checkboxes (default)"
-      v-slot="{ ariaDescribedby }"
-    >
-      <b-form-checkbox
-        v-for="option in options"
-        v-model="selected"
-        :key="option.value"
-        :value="option.value"
-        :aria-describedby="ariaDescribedby"
-        name="flavour-3a"
-      >
-        {{ option.text }}
-      </b-form-checkbox>
-    </b-form-group>
-
-    <b-form-group
-      label="Individual inline checkboxes"
-      v-slot="{ ariaDescribedby }"
-    >
-      <b-form-checkbox
-        v-for="option in options"
-        v-model="selected"
-        :key="option.value"
-        :value="option.value"
-        :aria-describedby="ariaDescribedby"
-        name="flavour-4a"
-        inline
-      >
-        {{ option.text }}
-      </b-form-checkbox>
-    </b-form-group>
-  </div>
-</template>
-
-<script>
-  export default {
-    data() {
-      return {
-        selected: [], // Must be an array reference!
-        options: [
-          { text: 'Orange', value: 'orange' },
-          { text: 'Apple', value: 'apple' },
-          { text: 'Pineapple', value: 'pineapple' },
-          { text: 'Grape', value: 'grape' }
-        ]
-      }
-    }
-  }
-</script>
-
-<!-- b-form-checkbox-stacked.vue -->
-```
-
-## Control sizing
-
-Use the `size` prop to control the size of the checkbox. The default size is medium. Supported size
-values are `sm` (small) and `lg` (large).
-
-```html
-<div>
-  <b-form-checkbox size="sm">Small</b-form-checkbox>
-  <b-form-checkbox>Default</b-form-checkbox>
-  <b-form-checkbox size="lg">Large</b-form-checkbox>
-</div>
-
-<!-- form-checkbox-sizes.vue -->
-```
-
-Sizes can be set on individual `<b-form-checkbox>` components, or inherited from the size setting of
-`<b-form-checkbox-group>`.
-
-**Note:** Bootstrap v4.x does not natively support sizes for the custom checkbox control. However,
-BootstrapVue includes custom SCSS/CSS that adds support for sizing the custom checkboxes.
-
-## Checkbox values and `v-model`
-
-By default, `<b-form-checkbox>` value will be `true` when checked and `false` when unchecked. You
-can customize the checked and unchecked values by specifying the `value` and `unchecked-value`
-properties, respectively.
-
-The `v-model` binds to the `checked` prop. When you have multiple checkboxes that bind to a single
-data state variable, you **must** provide an array reference (`[]`) to your `v-model`. Do not use
-the `checked` prop directly.
-
-Note that when `v-model` is bound to multiple checkboxes (i.e an array ref), the `unchecked-value`
-is **not used**. Only the value(s) of the checked checkboxes will be returned in the `v-model` bound
-array. You should provide a unique value for each checkbox's `value` prop (the default of `true`
-will not work when bound to an array)
-
-To pre-check any radios, set the `v-model` to the value(s) of the checks that you would like
-pre-selected.
-
-When placing individual `<b-form-checkbox>` components within a `<b-form-checkbox-group>`, most
-props and the `v-model` are inherited from the `<b-form-checkbox-group>`.
-
-**Note:** the `unchecked-value` prop _does not_ affect the native `<input>`'s `value` attribute,
-because browsers don't include unchecked boxes in form submissions. To guarantee that one of two
-values is submitted in a native `<form>` submit (e.g. `'yes'` or `'no'`), use radio inputs instead.
-This is the same limitation that
-[Vue has with native checkbox inputs](https://vuejs.org/v2/guide/forms.html#Checkbox-1).
-
-### Multiple checkboxes and accessibility
-
-When binding multiple checkboxes together, you must set the `name` prop to the same value for all
-`<b-form-checkbox>`s in the group individually or via the `name` prop of `<b-form-checkbox-group>`.
-This will inform users of assistive technologies that the checkboxes are related and enables native
-browser keyboard navigation.
-
-Whenever using multiple checkboxes, it is recommended that the checkboxes be placed in a
-[`<gl-form-group>`](?path=/docs/base-form-form-group--docs) component to associate a label with the
-entire group of checkboxes. See examples above.
-
-## Switch style checkboxes
-
-Switch styling is supported on `<b-form-checkbox>` and `<b-form-checkbox-group>` components.
-
-### Individual checkbox switch style
-
-A single checkbox can be rendered with a switch appearance by setting the prop `switch` to `true`
-
-```html
-<template>
-  <div>
-    <b-form-checkbox v-model="checked" name="check-button" switch>
-      Switch Checkbox <b>(Checked: {{ checked }})</b>
-    </b-form-checkbox>
-  </div>
-</template>
-
-<script>
-  export default {
-    data() {
-      return {
-        checked: false
-      }
-    }
-  }
-</script>
-
-<!-- b-form-checkbox-switch.vue -->
-```
-
-### Grouped switch style checkboxes
-
-Render groups of checkboxes with the look of a switches by setting the prop `switches` on
-`<b-form-checkbox-group>`.
-
-```html
-<template>
-  <div>
-    <b-form-group
-      label="Inline switch style checkboxes"
-      v-slot="{ ariaDescribedby }"
-    >
-      <b-form-checkbox-group
-        v-model="selected"
-        :options="options"
-        :aria-describedby="ariaDescribedby"
-        switches
-      ></b-form-checkbox-group>
-    </b-form-group>
-
-    <b-form-group
-      label="Stacked (vertical) switch style checkboxes"
-      v-slot="{ ariaDescribedby }"
-    >
-      <b-form-checkbox-group
-        v-model="selected"
-        :options="options"
-        :aria-describedby="ariaDescribedby"
-        switches
-        stacked
-      ></b-form-checkbox-group>
-    </b-form-group>
-  </div>
-</template>
-
-<script>
-  export default {
-    data() {
-      return {
-        selected: [], // Must be an array reference!
-        options: [
-          { text: 'Red', value: 'red' },
-          { text: 'Green', value: 'green' },
-          { text: 'Yellow (disabled)', value: 'yellow', disabled: true },
-          { text: 'Blue', value: 'blue' }
-        ]
-      }
-    }
-  }
-</script>
-
-<!-- b-form-checkboxes-switch-group.vue -->
-```
-
-### Switch sizing
-
-Use the `size` prop to control the size of the switch. The default size is medium. Supported size
-values are `sm` (small) and `lg` (large).
-
-```html
-<div>
-  <b-form-checkbox switch size="sm">Small</b-form-checkbox>
-  <b-form-checkbox switch>Default</b-form-checkbox>
-  <b-form-checkbox switch size="lg">Large</b-form-checkbox>
-</div>
-
-<!-- form-checkbox-switch-sizes.vue -->
-```
-
-Sizes can be set on individual `<b-form-checkbox>` components, or inherited from the size setting of
-`<b-form-checkbox-group>`.
-
-**Note:** Bootstrap v4.x does not natively support sizes for the custom switch control. However,
-BootstrapVue includes custom SCSS/CSS that adds support for sizing the custom switches.
-
-## Contextual states
-
-Bootstrap includes validation styles for `valid` and `invalid` states on most form controls.
-
-Generally speaking, you'll want to use a particular state for specific types of feedback:
-
-- `false` (denotes invalid state) is great for when there's a blocking or required field. A user
-  must fill in this field properly to submit the form.
-- `true` (denotes valid state) is ideal for situations when you have per-field validation throughout
-  a form and want to encourage a user through the rest of the fields.
-- `null` Displays no validation state (neither valid nor invalid)
-
-To apply one of the contextual state icons on `<b-form-checkbox>`, set the `state` prop to `false`
-(for invalid), `true` (for valid), or `null` (no validation state).
-
-### Contextual state and validation example
-
-```html
-<template>
-  <div>
-    <b-form-checkbox-group
-      v-model="value"
-      :options="options"
-      :state="state"
-      name="checkbox-validation"
-    >
-      <b-form-invalid-feedback :state="state">Please select two</b-form-invalid-feedback>
-      <b-form-valid-feedback :state="state">Thank you</b-form-valid-feedback>
-    </b-form-checkbox-group>
-  </div>
-</template>
-
-<script>
-  export default {
-    data() {
-      return {
-        value: [],
-        options: [
-          { text: 'First Check', value: 'first' },
-          { text: 'Second Check', value: 'second' },
-          { text: 'Third Check', value: 'third' }
-        ]
-      }
-    },
-    computed: {
-      state() {
-        return this.value.length === 2
-      }
-    }
-  }
-</script>
-
-<!-- form-checkbox-validation.vue -->
-```
-
-### Required constraint
-
-When using individual `<b-form-checkbox>` components (not in a `<b-form-checkbox-group>`), and you
-want the checkbox(es) to be `required` in your form, you **must** provide a `name` on each
-`<b-form-checkbox>` in order for the required constraint to work. All `<b-form-checkbox>` components
-tied to the same `v-model` **must** have the same `name`.
-
-The `name` is required in order for Assistive Technologies (such as screen readers, and keyboard
-only users) to know which checkboxes belong to the same form variable (the name also automatically
-enables native browser keyboard navigation), hence `required` will only work if `name` is set.
-`<b-form-checkbox-group>` will automatically generate a unique input name if one is not provided on
-the group.
-
-## Autofocus
-
-When the `autofocus` prop is set on `<b-form-checkbox>`, the input will be auto-focused when it is
-inserted (i.e. **mounted**) into the document, or re-activated when inside a Vue `<keep-alive>`
-component. Note that this prop **does not** set the `autofocus` attribute on the input, nor can it
-tell when the input becomes visible.
-
-## Indeterminate (tri-state) support
-
-Normally a checkbox input can only have two states: _checked_ or _unchecked_. They can have any
-value, but they either submit that value (_checked_) or don't (_unchecked_) with a form submission
-(although BootstrapVue allows a value for the _unchecked_ state on a single checkbox)
-
-_Visually_, there are actually three states a checkbox can be in: _checked_, _unchecked_, or
-**_indeterminate_**.
-
-The _indeterminate_ state is **visual only**. The checkbox is still either checked or unchecked as a
-value. That means the visual indeterminate state masks the real value of the checkbox, so that
-better make sense in your UI!
-
-`<b-form-checkbox>` supports setting this visual indeterminate state via the `indeterminate` prop
-(defaults to `false`). Clicking the checkbox will clear its indeterminate state. The `indeterminate`
-prop can be synced to the checkbox's state by v-binding the `indeterminate` prop with the `.sync`
-modifier.
-
-**Note:** indeterminate styling is not supported in switch mode, nor is it supported in
-`<b-form-checkbox-group>` (multiple checkboxes).
-
-**Single Indeterminate checkbox:**
-
-```html
-<template>
-  <div>
-    <b-form-checkbox v-model="checked" :indeterminate.sync="indeterminate">
-      Click me to see what happens
-    </b-form-checkbox>
-
-    <div class="mt-3">
-      Checked: <strong>{{ checked }}</strong><br>
-      Indeterminate: <strong>{{ indeterminate }}</strong>
-    </div>
-
-    <b-button @click="toggleIndeterminate">Toggle Indeterminate State</b-button>
-  </div>
-</template>
-
-<script>
-  export default {
-    data() {
-      return {
-        checked: true,
-        indeterminate: true
-      }
-    },
-    methods: {
-      toggleIndeterminate() {
-        this.indeterminate = !this.indeterminate
-      }
-    }
-  }
-</script>
-
-<!-- b-form-checkbox-indeterminate.vue -->
-```
-
-**Indeterminate checkbox use-case example:**
-
-```html
-<template>
-  <div>
-    <b-form-group>
-      <template #label>
-        <b>Choose your flavours:</b><br>
-        <b-form-checkbox
-          v-model="allSelected"
-          :indeterminate="indeterminate"
-          aria-describedby="flavours"
-          aria-controls="flavours"
-          @change="toggleAll"
-        >
-          {{ allSelected ? 'Un-select All' : 'Select All' }}
-        </b-form-checkbox>
-      </template>
-
-      <template v-slot="{ ariaDescribedby }">
-        <b-form-checkbox-group
-          id="flavors"
-          v-model="selected"
-          :options="flavours"
-          :aria-describedby="ariaDescribedby"
-          name="flavors"
-          class="ml-4"
-          aria-label="Individual flavours"
-          stacked
-        ></b-form-checkbox-group>
-      </template>
-    </b-form-group>
-
-    <div>
-      Selected: <strong>{{ selected }}</strong><br>
-      All Selected: <strong>{{ allSelected }}</strong><br>
-      Indeterminate: <strong>{{ indeterminate }}</strong>
-    </div>
-  </div>
-</template>
-
-<script>
-  export default {
-    data() {
-      return {
-        flavours: ['Orange', 'Grape', 'Apple', 'Lime', 'Very Berry'],
-        selected: [],
-        allSelected: false,
-        indeterminate: false
-      }
-    },
-    methods: {
-      toggleAll(checked) {
-        this.selected = checked ? this.flavours.slice() : []
-      }
-    },
-    watch: {
-      selected(newValue, oldValue) {
-        // Handle changes in individual flavour checkboxes
-        if (newValue.length === 0) {
-          this.indeterminate = false
-          this.allSelected = false
-        } else if (newValue.length === this.flavours.length) {
-          this.indeterminate = false
-          this.allSelected = true
-        } else {
-          this.indeterminate = true
-          this.allSelected = false
-        }
-      }
-    }
-  }
-</script>
-
-<!-- b-form-checkbox-indeterminate-multiple.vue -->
-```
-
-**Note:** Pay attention that plain checkbox (i.e. with prop `plain`) also supports indeterminate
-state on Windows/Linux/Mac/Android, but not on iOS.
-
-### Indeterminate state and accessibility
-
-Not all screen readers will convey the indeterminate state to screen reader users. So it is
-recommended to provide some form of textual feedback to the user (possibly by via the `.sr-only`
-class) if the indeterminate state has special contextual meaning in your application.
-
-<!-- Component reference added automatically from component package.json -->