bitboss-ui 2.1.113 → 2.1.115

package/dist/ai/BbDropzone.md

@@ -0,0 +1,504 @@
+# BbDropzone
+
+## Template & Script
+
+```vue
+<template>
+	<component :is="tag" :id="containerId" :class="classes">
+		<label
+			@dragenter.prevent="setDragging"
+			@dragleave.prevent="unsetDragging"
+			@dragover.prevent="onDragOver"
+			@drop.prevent="onDrop"
+		>
+			<input
+				:accept="acceptedMimeTypesString"
+				:autofocus="autofocus"
+				class="sr-only"
+				:disabled="disabled"
+				:multiple="multiple"
+				type="file"
+				@blur="onBlur"
+				@change="onChange"
+				@focus="onFocus"
+			/>
+			<slot v-bind="slotAttributes"></slot>
+		</label>
+		<label class="bb-dropzone__submittable-label">
+			Server files
+			<input
+				:id="id"
+				ref="submittable"
+				class="bb-dropzone__submittable-input"
+				:disabled="disabled"
+				:multiple="multiple"
+				:name="name"
+				type="file"
+			/>
+		</label>
+
+		<span class="bb-dropzone__errors">
+			<BbSmoothHeight tag="span">
+				<span
+					v-for="error in computedErrors"
+					:key="error"
+					class="bb-dropzone__error"
+					>{{ error }}</span
+				>
+			</BbSmoothHeight>
+		</span>
+	</component>
+</template>
+
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue';
+import { findInTree } from '@/utilities/functions/findInTree';
+import { useId } from '@/composables/useId';
+import BbSmoothHeight from '../BbSmoothHeight/BbSmoothHeight.vue';
+import type {
+	BbDropzoneProps,
+	BbDropzoneEvents,
+	BbDropzoneSlots,
+	DropZoneError,
+} from './types';
+export type {
+	BbDropzoneProps,
+	BbDropzoneEvents,
+	BbDropzoneSlots,
+	DropZoneError,
+};
+
+// This is the dynamic import for mime
+let mime: any;
+
+const props = withDefaults(defineProps<BbDropzoneProps>(), {
+	tag: 'div',
+});
+
+const emit = defineEmits<BbDropzoneEvents>();
+
+defineSlots<BbDropzoneSlots>();
+
+const submittable = ref<any | null>(null);
+
+if (props.accept) {
+	if (!Array.isArray(props.accept)) {
+		throw new Error('Property accept is not an array');
+	}
+}
+if (props.multiple) {
+	if (!Array.isArray(props.modelValue)) {
+		throw new Error(
+			'Component is set to multiple but modelValue is not an array'
+		);
+	}
+}
+
+const hasFocus = ref(false);
+const onFocus = (event: FocusEvent) => {
+	hasFocus.value = true;
+	emit('focus', event);
+};
+const onBlur = (event: FocusEvent) => {
+	hasFocus.value = false;
+	emit('blur', event);
+};
+
+/**  Allow dropzone to be submittable (this is flimsy and might break) */
+watch(
+	() => props.modelValue,
+	() => {
+		let container = new DataTransfer();
+		if (Array.isArray(props.modelValue)) {
+			if (props.modelValue.length) {
+				props.modelValue.forEach((file) => container.items.add(file));
+			}
+		} else {
+			if (props.modelValue) container.items.add(props.modelValue);
+		}
+		if (submittable.value) {
+			if (container.items.length) {
+				submittable.value.files = container.files;
+			} else {
+				submittable.value.files = null;
+			}
+		}
+	}
+);
+
+const acceptedMimeTypes = ref<string[]>([]);
+const acceptedMimeTypesString = computed(() =>
+	acceptedMimeTypes.value.join(',')
+);
+watch(
+	() => props.accept,
+	async () => {
+		if (props.accept) {
+			let accumulated = [];
+			for (let i = 0; i < props.accept.length; i++) {
+				const element = props.accept[i];
+				if (element.includes('/')) accumulated.push(element);
+				else {
+					if (!mime) {
+						const mod = await import('mime');
+						mime = mod.default;
+					}
+					const foundMime = mime.getType(element);
+					if (!foundMime) {
+						throw new Error(
+							`Could not detect the correct mime associated with ${element}`
+						);
+					}
+					accumulated.push(foundMime);
+				}
+			}
+			acceptedMimeTypes.value = accumulated;
+		}
+	},
+	{ immediate: true }
+);
+
+/**
+ * Component state
+ */
+const id = props.id || `${useId().id.value}`;
+const containerId = `bb_dz_${id}`;
+
+const dragging = ref(false);
+// Add a timeout to prevent browser flickering
+let draggingTimeout: ReturnType<typeof setTimeout>;
+
+const classes = computed(() => {
+	return {
+		'bb-dropzone': true,
+		'bb-dropzone--errors': hasErrors.value,
+		'bb-dropzone--dragging': dragging.value,
+	};
+});
+const slotAttributes = computed(() => {
+	return {
+		dragging: dragging.value,
+		focused: hasFocus.value,
+		id: id,
+	};
+});
+
+/**
+ * Component handlers
+ */
+const onDrop = (event: DragEvent) => {
+	dragging.value = false;
+
+	if (event.dataTransfer) {
+		event.stopImmediatePropagation();
+		let files;
+		files = Array.from(event.dataTransfer.files);
+		files = parseFiles(files);
+		if (props.multiple) {
+			if (Array.isArray(props.modelValue)) {
+				emit('update:modelValue', [...props.modelValue, ...files]);
+			}
+		} else {
+			files = files[0];
+			emit('update:modelValue', files);
+		}
+		if (event.currentTarget instanceof HTMLLabelElement) {
+			const innerInput = event.currentTarget.querySelector('input[type=file]');
+			if (innerInput instanceof HTMLInputElement) {
+				innerInput.focus();
+			}
+		}
+	}
+};
+const onChange = (event: Event) => {
+	if (event.target instanceof HTMLInputElement) {
+		if (event.target.files) {
+			let files;
+			files = parseFiles(Array.from(event.target.files));
+			if (props.multiple) {
+				if (Array.isArray(props.modelValue)) {
+					emit('update:modelValue', [...props.modelValue, ...files]);
+				}
+			} else {
+				files = files[0];
+				emit('update:modelValue', files);
+			}
+		}
+		event.target.value = '';
+		event.target.files = null;
+	}
+};
+
+const parseFiles = (files: File[]) => {
+	return files.filter((file, index) => {
+		// Sizecheck
+		if (props.maxSize) {
+			let passing = file.size <= props.maxSize;
+			if (!passing) {
+				emit('error', createError.maxSize(file));
+				return false;
+			}
+		}
+		// Uniqueness check
+		let alreadyExists = false;
+		if (props.modelValue) {
+			if (Array.isArray(props.modelValue)) {
+				alreadyExists = props.modelValue.some((current) =>
+					compareFiles(current, file)
+				);
+			} else {
+				alreadyExists = compareFiles(props.modelValue, file);
+			}
+		}
+		if (alreadyExists) {
+			emit('error', createError.uniqueness(file));
+			return false;
+		}
+		// Mime type check
+		if (props.accept) {
+			const mimePassed = acceptedMimeTypes.value.some((mime) => {
+				let found = false;
+				if (mime.includes('*'))
+					found = found || mime.split('/')[0] === file.type.split('/')[0];
+				else found = found || mime === file.type;
+				return found;
+			});
+			if (!mimePassed) {
+				emit('error', createError.accept(file));
+				return false;
+			}
+		}
+		// Max files check
+		if (props.maxFiles) {
+			if (Array.isArray(props.modelValue)) {
+				if (props.modelValue.length + index + 1 > props.maxFiles) {
+					emit(
+						'error',
+						createError.maxFiles(file, props.modelValue.length + index + 1)
+					);
+					return false;
+				}
+			}
+		}
+		return true;
+	});
+};
+
+const onDragOver = (event: Event) => {
+	// Find the closest dropzone in case of nested dropzones
+	const target = event.target;
+	if (target instanceof HTMLElement) {
+		const closestDropzone = findInTree([target], 'parentElement', (el) =>
+			el.classList.contains('bb-dropzone')
+		);
+		if (closestDropzone) {
+			/* When dragging over this dropzone set as dragging */
+			if (closestDropzone.id === containerId) {
+				setDragging();
+				/* When dragging over a nested dropzone do not highlight this dropzone */
+			} else {
+				unsetDragging();
+			}
+		}
+	}
+};
+
+const setDragging = () => {
+	clearTimeout(draggingTimeout);
+	dragging.value = true;
+};
+
+const unsetDragging = () => {
+	draggingTimeout = setTimeout(() => {
+		dragging.value = false;
+	}, 100);
+};
+
+const bytesToUnit = (bytes: number, decimals = 2) => {
+	if (!bytes) return '0 B';
+	const k = 1024;
+	const dm = decimals || 0;
+	const sizes = ['B', 'KB', 'MB', 'GB', 'TB', 'PB', 'EB', 'ZB', 'YB'];
+	const i = Math.floor(Math.log(bytes) / Math.log(k));
+	return parseFloat((bytes / Math.pow(k, i)).toFixed(dm)) + ' ' + sizes[i];
+};
+
+/**
+ * Returns true if files are identical by the properties that are accessible
+ * @param file The file to check
+ * @param otherFile The file to check against
+ */
+const compareFiles = (file: File, otherFile: File) => {
+	const properties: (keyof File)[] = ['name', 'size', 'lastModified', 'type'];
+	return !properties.some((key) => file[key] !== otherFile[key]);
+};
+
+/**
+ * Helper that creates errors based on component properties
+ */
+const createError = {
+	maxSize: (file: File) => {
+		// Todo update to isNil
+		if (props.maxSize) {
+			return {
+				type: 'maxSize',
+				file: file,
+				formattedMaxSize: bytesToUnit(+props.maxSize),
+				formattedSize: bytesToUnit(file.size),
+				filename: file.name,
+			} as const;
+		} else
+			throw new Error(
+				'Requested to create an error for maxSize without providing a maxSize.'
+			);
+	},
+	uniqueness: (file: File) => {
+		return {
+			type: 'uniqueness',
+			file: file,
+			filename: file.name,
+		} as const;
+	},
+	accept: (file: File) => {
+		return {
+			type: 'accept',
+			file: file,
+			acceptedMimeTypes: acceptedMimeTypes.value,
+			mimeType: file.type,
+			filename: file.name,
+		} as const;
+	},
+	maxFiles: (file: File, totalFiles: number) => {
+		return {
+			type: 'maxFiles',
+			file: file,
+			maxFiles: props.maxFiles,
+			totalFiles,
+			filename: file.name,
+		} as const;
+	},
+};
+
+const computedErrors = computed(() => {
+	return props.errors ? ([] as string[]).concat(props.errors) : [];
+});
+
+const hasErrors = computed(
+	() => Boolean(computedErrors.value.length) || props.hasErrors
+);
+</script>
+
+<style lang="postcss">
+@import './index.css';
+</style>
+```
+
+## Types
+
+```ts
+import type { CommonProps, NonVoidElementTag } from '@/types/CommonProps';
+
+export type DropZoneError =
+	| {
+			type: 'maxSize';
+			file: File;
+			formattedMaxSize: string;
+			formattedSize: string;
+			filename: string;
+	  }
+	| { type: 'uniqueness'; file: File; filename: string }
+	| {
+			type: 'accept';
+			file: File;
+			acceptedMimeTypes: string[];
+			mimeType: string;
+			filename: string;
+	  }
+	| {
+			type: 'maxFiles';
+			file: File;
+			maxFiles: number | undefined;
+			totalFiles: number;
+			filename: string;
+	  };
+
+export type BbDropzoneProps = Pick<
+	CommonProps,
+	'autofocus' | 'disabled' | 'errors' | 'hasErrors' | 'id' | 'multiple' | 'name'
+> & {
+	/**
+	 * Array of mime-types or extensions to filter selectable files.
+	 */
+	accept?: string[];
+	/**
+	 * Maximum number of acceptable files.
+	 */
+	maxFiles?: number;
+	/**
+	 * Max size of the files in bytes.
+	 */
+	maxSize?: number;
+	/**
+	 * Used by v-model.
+	 */
+	modelValue: any;
+} & NonVoidElementTag;
+
+export type BbDropzoneEvents = {
+	/** Emitted when the file input loses focus. Forwards the original DOM `FocusEvent`. */
+	(e: 'blur', event: FocusEvent): void;
+	/** Emitted when a file validation error occurs (e.g. size, type, uniqueness, max count). */
+	(e: 'error', data: DropZoneError): void;
+	/** Emitted when the file input receives focus. Forwards the original DOM `FocusEvent`. */
+	(e: 'focus', event: FocusEvent): void;
+	/** Emitted when the selected files change. Payload is the new file or file array. */
+	(e: 'update:modelValue', data: any): void;
+};
+
+/** Props exposed by the `default` slot. */
+export type BbDropzoneDefaultSlotProps = {
+	/** Whether a file is currently being dragged over the drop zone. */
+	dragging: boolean;
+	/** Whether the file input currently has keyboard focus. */
+	focused: boolean;
+	/** The `id` of the underlying file input, useful for custom label association. */
+	id: string;
+};
+
+export type BbDropzoneSlots = {
+	/**
+	 * The drop zone area content. Renders inside the `<label>` that captures drag and file input events.
+	 */
+	default?: (props: BbDropzoneDefaultSlotProps) => any;
+};
+```
+
+## Styles
+
+```css
+.bb-dropzone {
+	& > .bb-dropzone__submittable-label {
+		display: none;
+	}
+
+	& > label {
+		display: grid;
+	}
+
+	&.bb-dropzone--dragging {
+	}
+
+	&__errors {
+		color: var(--bb-danger);
+		display: grid;
+		font-size: 14px;
+		line-height: 18px;
+		width: 100%;
+	}
+
+	&__error {
+		display: inline-block;
+		width: 100%;
+	}
+}
+```