@gitlab/ui 84.1.0 → 85.0.0

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

@@ -0,0 +1,357 @@
+# Form File
+
+> Customized, cross-browser consistent, file input control that supports single file, multiple
+> files, and directory upload (for browsers that support directory mode).
+
+```html
+<template>
+  <div>
+    <!-- Styled -->
+    <b-form-file
+      v-model="file1"
+      :state="Boolean(file1)"
+      placeholder="Choose a file or drop it here..."
+      drop-placeholder="Drop file here..."
+    ></b-form-file>
+    <div class="mt-3">Selected file: {{ file1 ? file1.name : '' }}</div>
+
+    <!-- Plain mode -->
+    <b-form-file v-model="file2" class="mt-3" plain></b-form-file>
+    <div class="mt-3">Selected file: {{ file2 ? file2.name : '' }}</div>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        file1: null,
+        file2: null
+      }
+    }
+  }
+</script>
+
+<!-- b-form-file.vue -->
+```
+
+For cross browser consistency, `<b-form-file>` defaults to the Bootstrap custom file input to
+replace the browser defaults. They're built on top of semantic and accessible markup, so it is a
+solid replacement for the default file input.
+
+## Single file (default)
+
+On single file mode, when no file is selected or user cancels the "Browse" dialog, `v-model` is
+`null` indicating no file selected. When a file is selected the return value will be a JavaScript
+[`File`](https://developer.mozilla.org/en/docs/Web/API/File) object instance.
+
+## Multiple files
+
+Multiple file uploading is supported by adding `multiple` prop to component. In this case `v-model`
+is _always_ an `Array`. When no files are selected, an empty array will be returned. When a file or
+files are selected the return value will be an array of JavaScript
+[`File`](https://developer.mozilla.org/en/docs/Web/API/File) object instances.
+
+## Directory mode
+
+<div class="alert alert-warning small mb-3">
+  <p class="mb-0">
+    <strong>CAUTION:</strong> Directory mode is a <em>non-standard</em> feature. While being
+    supported by all modern browsers, it should not be relied on for production.
+    Read more on <a class="alert-link" href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLInputElement/webkitdirectory">MDN</a>
+    and <a class="alert-link" href="https://caniuse.com/input-file-directory">Can I use</a>.
+  </p>
+</div>
+
+By adding the `directory` prop, a user can select directories instead of files. When a directory is
+selected, the directory and its entire hierarchy of contents are included in the set of selected
+items.
+
+When in `directory` mode, files are returned in a nested array format by default. i.e.
+
+```
+dirA/
+  - fileA1
+  - fileA2
+  - dirB/
+    - fileB1
+  - dirC/
+    - fileC1
+    - fileC2
+dirD/
+  - fileD1
+```
+
+will be returned as (or similar, file/directory order may vary):
+
+```
+[[fileA1, fileA2, [fileB1], [fileC1, fileC2]], [fileD1]]
+```
+
+If you set the `no-traverse` prop, the array will be flattened:
+
+```
+[fileA1, fileA2, fileB1, fileC1, fileC2, fileD1]
+```
+
+Each file entry will have a special `$path` prop that will contain the relative path of each file.
+For nested directory structures, BootstrapVue uses its own routine to determine the relative path,
+otherwise it relies on
+[`File.webkitRelativePath`](https://developer.mozilla.org/en-US/docs/Web/API/File/webkitRelativePath).
+
+Directory mode is also supported when the file input is in [`plain` mode](#non-custom-file-input) on
+**most** modern browsers.
+
+## Drag and Drop support
+
+Drop mode is enabled by default. It can disabled by setting the `no-drop` prop. `no-drop` has no
+effect in [`plain` mode](#non-custom-file-input) (some browsers support dropping files onto a plain
+input file).
+
+You can optionally set a different placeholder while dragging via the `drop-placeholder` prop or the
+scoped `drop-placeholder` slot. The prop only supports plain text. Use the slot for custom HTML
+markup. The slot takes precedence over the prop. The `drop-placeholder` prop/slot has no effect if
+`no-drop` is set or in [`plain` mode](#non-custom-file-input).
+
+Note that native browser constraints (such as `required`) will not work with drop mode, as the
+hidden file input does not handle the drag and drop functionality and will have zero files selected.
+
+## Limiting to certain file types
+
+You can limit the file types by setting the `accept` prop to a string containing the allowed file
+type(s). To specify more than one type, separate the values with a comma.
+
+```html
+<div>
+  <!-- Accept all image formats by IANA media type wildcard-->
+  <b-form-file accept="image/*"></b-form-file>
+
+  <!-- Accept specific image formats by IANA type -->
+  <b-form-file accept="image/jpeg, image/png, image/gif"></b-form-file>
+
+  <!-- Accept specific image formats by extension -->
+  <b-form-file accept=".jpg, .png, .gif"></b-form-file>
+</div>
+```
+
+To accept any file type, leave `accept` as `null` (default). You can mix and match IANA media types
+and extensions.
+
+Refer to [IANA Media Types](https://www.iana.org/assignments/media-types/) for a complete list of
+standard media types.
+
+**Note:** Not all browsers support or respect the `accept` attribute on file inputs.
+
+For drag and drop, BootstrapVue uses an internal file type checking routine and will filter out
+files that do not have the correct IANA media type or extension.
+
+## Customizing
+
+`<b-form-file>`, when not in [`plain` mode](#non-custom-file-input), provides several features for
+customizing its appearance.
+
+### Control sizing
+
+Use the `size` prop to control the visual size of the input. The default size is considered `md`
+(medium). Optional sizes are `lg` (large) and `sm` (small). These sizes line up with the sizes
+available on other form controls.
+
+```html
+<div>
+  <b-form-group label="Small:" label-cols-sm="2" label-size="sm">
+    <b-form-file id="file-small" size="sm"></b-form-file>
+  </b-form-group>
+
+  <b-form-group label="Default:" label-cols-sm="2">
+    <b-form-file id="file-default"></b-form-file>
+  </b-form-group>
+
+  <b-form-group label="Large:" label-cols-sm="2" label-size="lg">
+    <b-form-file id="file-large" size="lg"></b-form-file>
+  </b-form-group>
+</div>
+
+<!-- form-file-sizes.vue -->
+```
+
+**Note:** Bootstrap v4.x does not natively support sizes for the custom file control. However,
+BootstrapVue includes custom SCSS/CSS that adds support for sizing the custom file input control.
+
+### Customize the placeholder text
+
+Use the `placeholder` prop or the scoped `placeholder` slot to change the prompt text that is shown
+when no files are selected. The prop only supports plain text. Use the slot for custom HTML markup.
+The slot takes precedence over the prop.
+
+### Customize browse button label
+
+If you want to globally change `Browse` label, you can add something like this to your global
+stylesheets. Also it is advised to use
+[:lang()](https://developer.mozilla.org/en-US/docs/Web/CSS/:lang) for multi-language sites.
+
+```css
+.custom-file-input:lang(en) ~ .custom-file-label::after {
+  content: 'Browse';
+}
+```
+
+Alternatively you can set the content of the custom file browse button text via the `browse-text`
+prop. Note, only plain text is supported. HTML and components are not supported.
+
+### File name formatter function
+
+Set the prop `file-name-formatter` to a function that accepts three arguments:
+
+| Argument             | Type  | Description                                                                   |
+| -------------------- | ----- | ----------------------------------------------------------------------------- |
+| [1] `files`          | Array | Flat array of `File` objects                                                  |
+| [2] `filesTraversed` | Array | Array of arrays of `File` objects when in [`directory` mode](#directory-mode) |
+| [3] `names`          | Array | Flat array of file names (strings)                                            |
+
+The function should return a single formatted string (HTML is not supported). The formatter will not
+be called if no files are selected.
+
+```html
+<template>
+  <b-form-file multiple :file-name-formatter="formatNames"></b-form-file>
+</template>
+
+<script>
+  export default {
+    methods: {
+      formatNames(files) {
+        return files.length === 1 ? files[0].name : `${files.length} files selected`
+      }
+    }
+  }
+</script>
+
+<!-- file-formatter-function.vue -->
+```
+
+### File name formatting via scoped slot
+
+Alternatively, you can use the scoped slot `file-name` to render the file names. The scoped slot
+will receive the following properties:
+
+| Property         | Type  | Description                                                                   |
+| ---------------- | ----- | ----------------------------------------------------------------------------- |
+| `files`          | Array | Flat array of `File` objects                                                  |
+| `filesTraversed` | Array | Array of arrays of `File` objects when in [`directory` mode](#directory-mode) |
+| `names`          | Array | Flat array of file names (strings)                                            |
+
+All three properties are always arrays, regardless of the setting of the `multiple` prop.
+
+```html
+<template>
+  <b-form-file multiple>
+   <template slot="file-name" slot-scope="{ names }">
+     <b-badge variant="dark">{{ names[0] }}</b-badge>
+     <b-badge v-if="names.length > 1" variant="dark" class="ml-1">
+       + {{ names.length - 1 }} More files
+     </b-badge>
+   </template>
+  </b-form-file>
+</template>
+
+<!-- file-formatter-slot.vue -->
+```
+
+When using the `file-name` slot, the `file-name-formatter` prop is ignored. The slot **will not** be
+rendered when there are no file(s) selected.
+
+## Non custom file input
+
+You can have `<b-form-file>` render a browser native file input by setting the `plain` prop. Note
+that many of the custom features do not apply when `plain` is set.
+
+## Contextual state feedback
+
+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-file>`, set the `state` prop to `false` (for
+invalid), `true` (for valid), or `null` (no validation state).
+
+**Note:** Contextual states are **not** supported when in [`plain` mode](#non-custom-file-input).
+
+## Autofocus
+
+When the `autofocus` prop is set on `<b-form-file>`, 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.
+
+## Accessibility
+
+When using the custom version of `<b-form-file>` input which hides the original input, it is
+**highly recommended** that you supply a document unique ID string via the `id` prop. This will
+automatically render the extra ARIA attributes required to improve usability for persons using
+assistive technologies.
+
+## Clearing the file selection
+
+With inputs of type file, normally the `v-model` is uni-directional (meaning you cannot pre-set the
+selected files). However, you can clear the file input's selected files by setting the `v-model` to
+either `null` (for single mode) or an empty array `[]` (for
+[`multiple`](#multiple-files)/[`directory`](#directory-mode) mode).
+
+Alternatively, `<b-form-file>` provides a `reset()` method that can be called to clear the file
+input. To take advantage of the `reset()` method, you will need to obtain a reference to the
+`<b-form-file>` component.
+
+```html
+<template>
+  <div>
+    <b-form-file v-model="file" ref="file-input" class="mb-2"></b-form-file>
+
+    <b-button @click="clearFiles" class="mr-2">Reset via method</b-button>
+    <b-button @click="file = null">Reset via v-model</b-button>
+
+    <p class="mt-2">Selected file: <b>{{ file ? file.name : '' }}</b></p>
+  </div>
+</template>
+
+<script>
+  export default {
+    data() {
+      return {
+        file: null
+      }
+    },
+    methods: {
+      clearFiles() {
+        this.$refs['file-input'].reset()
+      }
+    }
+  }
+</script>
+
+<!-- b-form-file-reset.vue -->
+```
+
+## Implementation notes
+
+As not all browsers allow setting a value of a file input (even to `null` or an empty string),
+`b-form-input` employs a technique that works cross-browser that involves changing the input type to
+`null` and then immediately back to type `file`.
+
+Nested file structures in [`directory` mode](#directory-mode) require `Promise` support in the
+browser. If targeting your app for older browsers, such as IE 11, please include a polyfill that
+provides `Promise` support. If `Promise` support is not detected, files will always be in a flat
+file structure.
+
+Due to a ["bug" in Chromium](https://bugs.chromium.org/p/chromium/issues/detail?id=138987), nested
+file structures in [`directory` mode](#directory-mode) are currently only supported when directories
+are [dropped](#drag-and-drop-support) on the file input. When selecting them via the "Browse" dialog
+they will always be in a flattened array structure. Mozilla implemented the behavior
+[the same way as Chromium.](https://bugzilla.mozilla.org/show_bug.cgi?id=1326031)
+
+<!-- Component reference added automatically from component package.json -->

package/src/vendor/bootstrap-vue/src/components/form-file/_form-file.scss

@@ -0,0 +1,61 @@
+// Adds in sizes for custom-file
+
+// Prevent file names from overflowing the file input
+// These styles can be removed when the related Bootstrap bug gets fixed:
+// https://github.com/twbs/bootstrap/issues/31577
+.custom-file-label {
+  white-space: nowrap;
+  overflow-x: hidden;
+}
+
+.b-custom-control-lg,
+.input-group-lg {
+  &.custom-file,
+  .custom-file-input,
+  .custom-file-label {
+    font-size: $b-custom-file-font-size-lg;
+    height: $b-custom-file-height-lg;
+  }
+
+  .custom-file-label,
+  .custom-file-label:after {
+    padding: $b-custom-file-padding-y-lg $b-custom-file-padding-x-lg;
+    line-height: $b-custom-file-line-height-lg;
+  }
+
+  .custom-file-label {
+    @include border-radius($b-custom-file-border-radius-lg);
+
+    &::after {
+      font-size: inherit;
+      height: $b-custom-file-height-inner-lg;
+      @include border-radius(0 $b-custom-file-border-radius-lg $b-custom-file-border-radius-lg 0);
+    }
+  }
+}
+
+.b-custom-control-sm,
+.input-group-sm {
+  &.custom-file,
+  .custom-file-input,
+  .custom-file-label {
+    font-size: $b-custom-file-font-size-sm;
+    height: $b-custom-file-height-sm;
+  }
+
+  .custom-file-label,
+  .custom-file-label:after {
+    padding: $b-custom-file-padding-y-sm $b-custom-file-padding-x-sm;
+    line-height: $b-custom-file-line-height-sm;
+  }
+
+  .custom-file-label {
+    @include border-radius($b-custom-file-border-radius-sm);
+
+    &::after {
+      font-size: inherit;
+      height: $b-custom-file-height-inner-sm;
+      @include border-radius(0 $b-custom-file-border-radius-sm $b-custom-file-border-radius-sm 0);
+    }
+  }
+}