@carbon/vue 3.0.6-alpha.0 → 3.0.8-alpha.0

package/src/components/CvFileUploader/CvFileUploader.stories.mdx

@@ -0,0 +1,333 @@
+import { Canvas, Meta, Story } from '@storybook/addon-docs';
+import { sbCompPrefix } from '../../global/storybook-utils';
+import { CvFileUploader, CvFileUploaderSkeleton } from '.';
+import { KINDS } from './const';
+import { action } from '@storybook/addon-actions';
+import { nextTick, ref } from 'vue';
+import { Add16 } from '@carbon/icons-vue';
+import { buttonKinds, buttonSizes } from '../CvButton/consts';
+
+<Meta title={`${sbCompPrefix}/CvFileUploader`} component={CvFileUploader} />
+
+export const Template = args => ({
+  components: {
+    CvFileUploader,
+    CvFileUploaderSkeleton,
+    Add16
+  },
+  setup() {
+    return {
+      slotContent: args.slot,
+      args: {
+        ...args,
+        template: undefined,
+      },
+    };
+  },
+  template: args.template,
+});
+const defaultTemplate = `
+  <div style="display: inline-flex; align-items: flex-start;">
+    <cv-file-uploader v-bind="args" />
+  </div>
+`;
+const slotTemplate = `
+  <div style="display: inline-flex; align-items: flex-start;">
+    <cv-file-uploader v-bind="args">
+      <template v-slot:drop-target>
+        <Add16 />
+        <span>File Drop</span>
+        <Add16 />
+      </template>
+    </cv-file-uploader>
+  </div>
+`;
+const skeletonTemplate = `
+  <div style="display: inline-flex; align-items: flex-start;">
+    <cv-file-uploader-skeleton />
+  </div>
+`;
+
+export const args = {
+  // attributes
+  multiple: {
+    type: 'boolean',
+    table: {
+      type: { summary: 'boolean' },
+      category: 'attributes',
+    },
+    description: 'standard input attribute for file type, allow multiple files to be added in a single prompt',
+  },
+  // props
+  accept: {
+    type: 'string',
+    table: {
+      type: { summary: 'string' },
+      category: 'props',
+    },
+    description: 'standard input attribute for file type',
+  },
+  buttonKind: {
+    control: 'select',
+    options: buttonKinds,
+    defaultValue: 'primary',
+    table: {
+      type: { summary: 'string' },
+      category: 'props',
+      defaultValue: { summary: 'primary' },
+    },
+    description: 'Button kind',
+  },
+  buttonLabel: {
+    type: 'string',
+    deprecated: true,
+    table: {
+      type: { summary: 'string' },
+      category: 'props',
+    },
+    description: '`button-label` prop deprecated in favour of drop-target-label',
+  },
+  buttonSize: {
+    control: 'select',
+    options: buttonSizes,
+    defaultValue: '',
+    table: {
+      type: { summary: 'string' },
+      category: 'props',
+      defaultValue: { summary: '' },
+    },
+    description: 'Button size',
+  },
+  clearOnReselect: {
+    type: 'boolean',
+    table: {
+      type: { summary: 'boolean' },
+      category: 'props',
+    },
+    description: 'Reset file list when files are added',
+  },
+  dropTargetLabel: {
+    type: 'string',
+    table: {
+      type: { summary: 'string' },
+      category: 'props',
+    },
+    description: "Drag & drop zone label. Also used as button label for button kind file uploader",
+  },
+  helperText: {
+    type: 'string',
+    table: {
+      type: { summary: 'string' },
+      category: 'props',
+    },
+    description: 'Helper text positioned below label',
+  },
+  kind: {
+    type: 'string',
+    control: 'select',
+    defaultValue: KINDS.DRAG_TARGET,
+    options: [KINDS.DRAG_TARGET, KINDS.BUTTON],
+    table: {
+      type: { summary: `${KINDS.DRAG_TARGET} | ${KINDS.BUTTON}` },
+      category: 'props',
+      defaultValue: { summary: KINDS.DRAG_TARGET },
+    },
+    description: 'Kind of file uploader to present',
+  },
+  label: {
+    table: {
+      type: { summary: 'text' },
+      category: 'props',
+    },
+    description: 'File input label',
+  },
+  removable: {
+    type: 'boolean',
+    table: {
+      type: { summary: 'boolean' },
+      category: 'props',
+    },
+    description: 'Enable file items remove button',
+  },
+  removeAriaLabel: {
+    type: 'string',
+    defaultValue: 'Remove selected file',
+    table: {
+      type: { summary: 'string' },
+      category: 'props',
+      defaultValue: { summary: 'Remove selected file' },
+    },
+    description: 'Aria label for item remove button',
+  },
+  // exposed methods
+  clear: {
+    control: 'none',
+    type: 'function',
+    table: {
+      type: { summary: '() => void' },
+      category: 'exposed methods',
+    },
+    description: 'Clear file list',
+  },
+  remove: {
+    control: 'none',
+    type: 'function',
+    table: {
+      type: { summary: '(index: number) => void' },
+      category: 'exposed methods',
+    },
+    description: 'Removes an individual file',
+  },
+  setState: {
+    control: 'none',
+    type: 'function',
+    table: {
+      type: { summary: '(index: number, state: string) => void' },
+      category: 'exposed methods',
+    },
+    description: 'Update the "state" field of a file. State must be `""`, `complete` or `loading`',
+  },
+  setInvalidMessage: {
+    control: 'none',
+    type: 'function',
+    table: {
+      type: { summary: '(index: number, invalidMessage: string) => void' },
+      category: 'exposed methods',
+    },
+    description: 'Update the "invalidMessage" field of a file.',
+  },
+  // slots
+  'drop-target': {
+    control: 'none',
+    type: 'string',
+    table: {
+      type: { summary: 'string | HTML | Component' },
+      category: 'slots',
+    },
+    description: 'Overrides the drop-target-label with slotted content',
+  },
+};
+
+# CvFileUploader
+
+Migration notes:
+
+- The `v-model` is different in Vue 3 than Vue 2. You can still specify the `v-model="something"` for two way data bind,
+  but the value property is now `modelValue` instead of `files` and event linked to v-model is `update:modelValue`.
+
+<Canvas>
+  <Story
+    name="Default"
+    parameters={{
+      controls: {
+        exclude: [
+          'template',
+          'props',
+          'modelValue',
+          'update:modelValue',
+        ],
+      },
+      docs: { source: { code: defaultTemplate } },
+    }}
+    args={{
+      template: defaultTemplate,
+      label: 'Choose files to upload',
+      helperText: 'Select the files you want to upload',
+      removable: true,
+    }}
+    argTypes={args}
+  >
+    {Template.bind({})}
+  </Story>
+</Canvas>
+
+# CvFileUploader Button
+
+<Canvas>
+  <Story
+    name="FilerUploader Button"
+    parameters={{
+      controls: {
+        exclude: [
+          'template',
+          'props',
+          'modelValue',
+          'update:modelValue',
+        ],
+      },
+      docs: { source: { code: defaultTemplate } },
+    }}
+    args={{
+      template: defaultTemplate,
+      label: 'Choose files to upload',
+      helperText: 'Select the files you want to upload',
+      kind: KINDS.BUTTON,
+      removable: true,
+    }}
+    argTypes={{
+      ...args,
+      kind: {
+        ...args.kind,
+        control: 'none',
+      },
+    }}
+  >
+    {Template.bind({})}
+  </Story>
+</Canvas>
+
+# CvFileUploader Slotted
+
+<Canvas>
+  <Story
+    name="Slot"
+    parameters={{
+      controls: {
+        exclude: [
+          'template',
+          'props',
+          'modelValue',
+          'update:modelValue',
+        ],
+      },
+      docs: { source: { code: slotTemplate } },
+    }}
+    args={{
+      template: slotTemplate,
+      label: 'Choose files to upload',
+      helperText: 'Select the files you want to upload',
+      removable: true,
+    }}
+    argTypes={{
+      ...args,
+      kind: {
+        ...args.kind,
+        control: 'none',
+      },
+    }}
+  >
+    {Template.bind({})}
+  </Story>
+</Canvas>
+
+# CvFileUploaderSkeleton
+
+<Canvas>
+  <Story
+    name="Skeleton"
+    parameters={{
+      controls: {
+        exclude: [
+          'template',
+        ],
+      },
+      docs: { source: { code: skeletonTemplate } },
+    }}
+    args={{
+      template: skeletonTemplate,
+    }}
+    argTypes={{}}
+  >
+    {Template.bind({})}
+  </Story>
+</Canvas>

package/src/components/CvFileUploader/CvFileUploader.vue

@@ -0,0 +1,286 @@
+<template>
+  <cv-form-item class="cv-file-uploader">
+    <p :class="`${carbonPrefix}--file--label`">{{ label }}</p>
+    <p :class="`${carbonPrefix}--label-description`">{{ helperText }}</p>
+    <div v-if="kind === 'button'" :class="`${carbonPrefix}--file`" data-file>
+      <label
+        :for="cvId"
+        :class="buttonClasses"
+        tabindex="0"
+        @keydown.enter.prevent="onKeyHit"
+        @keydown.space.prevent="onKeyHit"
+      >
+        <slot name="drop-target">{{ internalDropTargetLabel }}</slot>
+      </label>
+      <input
+        :id="cvId"
+        ref="fileInput"
+        :class="`${carbonPrefix}--file-input`"
+        :accept="accept"
+        type="file"
+        v-bind="$attrs"
+        data-file-uploader
+        data-target="[data-file-container]"
+        @change="onChange"
+      />
+    </div>
+    <div v-else :class="`${carbonPrefix}--file`" data-file>
+      <label :for="cvId">
+        <div
+          role="button"
+          tabindex="0"
+          data-file-drop-container
+          :class="[
+            `${carbonPrefix}--file-browse-btn`,
+            `${carbonPrefix}--file__drop-container`,
+            {
+              [`${carbonPrefix}--file__drop-container--drag-over`]: allowDrop,
+            },
+          ]"
+          @dragover="onDragEvent"
+          @dragleave="onDragEvent"
+          @drop="onDragEvent"
+          @keydown.enter.prevent="onKeyHit"
+          @keydown.space.prevent="onKeyHit"
+        >
+          <slot name="drop-target">{{ internalDropTargetLabel }}</slot>
+        </div>
+        <input
+          :id="cvId"
+          ref="fileInput"
+          :class="`${carbonPrefix}--file-input`"
+          :accept="accept"
+          type="file"
+          v-bind="$attrs"
+          tabindex="-1"
+          data-file-uploader
+          data-target="[data-file-container]"
+          @change="onChange"
+        />
+      </label>
+    </div>
+    <div
+      :class="`${carbonPrefix}--file ${carbonPrefix}--file-container`"
+      data-file-container
+    >
+      <cv-file-uploader-item
+        v-for="(item, index) in internalFiles"
+        :key="item.file.name"
+        :item="item"
+        :removable="removable"
+        :removeAriaLabel="removeAriaLabel"
+        @remove="onItemRemove(index)"
+      />
+    </div>
+  </cv-form-item>
+</template>
+
+<script setup>
+import { ref, computed, onMounted, watch } from 'vue';
+import CvFileUploaderItem from './CvFileUploaderItem.vue';
+import { carbonPrefix } from '../../global/settings';
+import { CvFormItem } from '../CvForm';
+import { useCvId, props as cvIdProps } from '../../use/cvId';
+import { KINDS, STATES } from './const';
+import {
+  props as commonCvButtonProps,
+  useCvButtonCommon,
+} from '../CvButton/CvButtonCommon';
+
+const emit = defineEmits(['update:modelValue']);
+
+const props = defineProps({
+  accept: String,
+  buttonKind: commonCvButtonProps.kind,
+  buttonLabel: {
+    type: String,
+    default: undefined,
+    deprecated: true,
+    validator: val => {
+      if (val !== undefined && process.env.NODE_ENV === 'development') {
+        console.warn(
+          'CvFileUploader: button-label prop deprecated in favour of drop-target-label'
+        );
+      }
+      return true;
+    },
+  },
+  buttonSize: commonCvButtonProps.size,
+  clearOnReselect: Boolean,
+  dropTargetLabel: String,
+  helperText: String,
+  kind: {
+    type: String,
+    default: KINDS.DRAG_TARGET,
+    validator: val => {
+      const validValues = Object.values(KINDS);
+      if (!validValues.includes(val)) {
+        console.warn(
+          `CvFileUploader: valid values for 'kind' are ${validValues}`
+        );
+      }
+      return true;
+    },
+  },
+  label: String,
+  modelValue: Array,
+  removable: Boolean,
+  removeAriaLabel: String,
+  ...cvIdProps,
+});
+
+// DOM Elements
+const fileInput = ref(null);
+
+// Data
+const allowDrop = ref(false);
+const internalFiles = ref([]);
+
+// Computed
+const { buttonClasses } = useCvButtonCommon(props.buttonKind, props.buttonSize);
+const cvId = useCvId(props);
+const internalDropTargetLabel = computed(() => {
+  return (
+    props.dropTargetLabel ||
+    props.buttonLabel ||
+    'Drag and drop files here or upload'
+  );
+});
+const isFileTypeAllowed = computed(() => {
+  const acceptAny = !props.accept;
+  const allowedTypes = props.accept
+    ? props.accept.split(',').map(x => x.trim())
+    : [];
+  if (allowedTypes.includes('.jpg')) {
+    allowedTypes.push('.jpeg');
+  }
+  return file => {
+    if (acceptAny) return true;
+    const extension = '.' + file.name.split('.').pop();
+    return allowedTypes.includes(file.type) || allowedTypes.includes(extension);
+  };
+});
+
+// Watchers
+watch(
+  () => props.modelValue,
+  newValue => {
+    internalFiles.value = newValue || [];
+  }
+);
+
+// Methods
+function addFiles(files) {
+  for (const file of files) {
+    const internalFile = internalFiles.value.find(
+      item => item.file.name === file.name
+    );
+    const newFile = createInternalFile(internalFile?.file || file);
+
+    if (internalFile) {
+      internalFile.state = newFile.initialState;
+      internalFile.invalidMessageTitle = newFile.invalidMessageTitle;
+      internalFile.invalidMessage = newFile.invalidMessage;
+    } else {
+      internalFiles.value.push(newFile);
+    }
+  }
+  // clear input we do not need to maintain it
+  fileInput.value.value = '';
+  emit('update:modelValue', internalFiles.value);
+}
+
+function createInternalFile(file) {
+  const initialState = props.initialStateUploading
+    ? STATES.UPLOADING
+    : STATES.NONE;
+  const isTypeNotAllowed = !isFileTypeAllowed.value(file);
+  const invalidMessageTitle = isTypeNotAllowed ? 'Invalid file type' : '';
+  const invalidMessage = isTypeNotAllowed
+    ? `"${file.name}" does not have a valid file type.`
+    : '';
+
+  return {
+    state: initialState,
+    file,
+    invalidMessageTitle,
+    invalidMessage,
+  };
+}
+
+function onChange(ev) {
+  if (ev.target.files.length !== 0 && props.clearOnReselect) {
+    internalFiles.value = [];
+  }
+  addFiles(ev.target.files);
+}
+
+function onDragEvent(evt) {
+  if (Array.prototype.indexOf.call(evt.dataTransfer.types, 'Files') === -1) {
+    return;
+  }
+
+  if (evt.type === 'dragleave') {
+    allowDrop.value = false;
+    return;
+  }
+
+  if (evt.type === 'dragover') {
+    evt.preventDefault();
+    const dropEffect = 'copy';
+    if (Array.isArray(evt.dataTransfer.types)) {
+      try {
+        // IE11 throws a "permission denied" error accessing `.effectAllowed`
+        evt.dataTransfer.effectAllowed = dropEffect;
+      } catch (e) {
+        // ignore
+      }
+    }
+    evt.dataTransfer.dropEffect = dropEffect;
+    allowDrop.value = true;
+  }
+
+  if (evt.type === 'drop') {
+    evt.preventDefault();
+    addFiles(evt.dataTransfer.files);
+    allowDrop.value = false;
+  }
+}
+
+function onItemRemove(index) {
+  internalFiles.value.splice(index, 1);
+  emit('update:modelValue', this.internalFiles);
+}
+
+function onKeyHit() {
+  fileInput.value.click();
+}
+
+// Lifecycle Hooks
+onMounted(() => {
+  internalFiles.value = props.modelValue || [];
+});
+
+// exposed methods
+defineExpose({
+  setState(index, state) {
+    if ([STATES.COMPLETE, STATES.UPLOADING, STATES.NONE].includes(state)) {
+      internalFiles.value[index].state = state;
+    }
+  },
+  clear() {
+    internalFiles.value = [];
+    emit('update:modelValue', internalFiles);
+  },
+  setInvalidMessage(index, message) {
+    internalFiles.value[index].invalidMessage = message;
+  },
+  remove: onItemRemove,
+});
+</script>
+
+<script>
+export default {
+  inheritAttrs: false,
+};
+</script>

package/src/components/CvFileUploader/CvFileUploaderItem.vue

@@ -0,0 +1,92 @@
+<template>
+  <div
+    :class="[
+      `${carbonPrefix}--file__selected-file`,
+      { [`${carbonPrefix}--file__selected-file--invalid`]: isInvalid },
+    ]"
+  >
+    <p :class="`${carbonPrefix}--file-filename`" :title="item.file?.name">
+      {{ item.file?.name }}
+    </p>
+    <span :class="`${carbonPrefix}--file__state-container`">
+      <div
+        v-if="item.state === 'uploading'"
+        :class="`${carbonPrefix}--inline-loading__animation`"
+      >
+        <div
+          data-inline-loading-spinner
+          :class="`${carbonPrefix}--loading ${carbonPrefix}--loading--small`"
+        >
+          <svg
+            :class="`${carbonPrefix}--loading__svg`"
+            viewBox="-75 -75 150 150"
+          >
+            <circle
+              :class="`${carbonPrefix}--loading__background`"
+              cx="0"
+              cy="0"
+              r="37.5"
+            />
+            <circle
+              :class="`${carbonPrefix}--loading__stroke`"
+              cx="0"
+              cy="0"
+              r="37.5"
+            />
+          </svg>
+        </div>
+      </div>
+      <CheckmarkFilled16
+        v-if="item.state === 'complete'"
+        :class="`${carbonPrefix}--file-complete`"
+      />
+      <WarningFilled16
+        v-if="isInvalid"
+        :class="`${carbonPrefix}--file--invalid`"
+      />
+      <button
+        v-if="removable"
+        type="button"
+        :class="`${carbonPrefix}--file-close`"
+        :alt="removeAriaLabel"
+        :arial-label="removeAriaLabel"
+        @click="emit('remove', item)"
+      >
+        <Close16 />
+        <span :class="`${carbonPrefix}--visually-hidden`">
+          {{ removeAriaLabel }}
+        </span>
+      </button>
+    </span>
+    <!-- check role (alert) and id / accessibility -->
+    <div v-if="isInvalid" :class="`${carbonPrefix}--form-requirement`">
+      <div :class="`${carbonPrefix}--form-requirement__title`">
+        {{ item.invalidMessageTitle || 'Invalid file' }}
+      </div>
+      <p :class="`${carbonPrefix}--form-requirement__supplement`">
+        {{ item.invalidMessage }}
+      </p>
+    </div>
+  </div>
+</template>
+
+<script setup>
+import { computed } from 'vue';
+import { carbonPrefix } from '../../global/settings';
+import CheckmarkFilled16 from '@carbon/icons-vue/es/checkmark--filled/16';
+import WarningFilled16 from '@carbon/icons-vue/es/warning--filled/16';
+import Close16 from '@carbon/icons-vue/es/close/16';
+
+const emit = defineEmits(['remove']);
+
+const props = defineProps({
+  item: Object,
+  removable: Boolean,
+  removeAriaLabel: { type: String, default: 'Remove selected file' },
+});
+
+// Computed
+const isInvalid = computed(() => {
+  return props.item.invalidMessage && props.item.invalidMessage.length;
+});
+</script>