handy-uploader 2.0.3 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (38) hide show
  1. package/README.md +290 -292
  2. package/dist/components/handyUploader.vue.d.ts +3 -3
  3. package/dist/composables/deprecation.d.ts +2 -0
  4. package/dist/composables/useErrorHandler.d.ts +4 -0
  5. package/dist/composables/useFileUpload.d.ts +5 -0
  6. package/dist/core/attachments.d.ts +91 -0
  7. package/dist/core/fileUtils.d.ts +56 -0
  8. package/dist/core/index.d.ts +3 -0
  9. package/dist/core/videoThumbnail.d.ts +32 -0
  10. package/dist/element/HandyUploaderElement.d.ts +20 -0
  11. package/dist/element/index.d.ts +21 -0
  12. package/dist/element/types.d.ts +108 -0
  13. package/dist/element.mjs +6178 -0
  14. package/dist/handy-uploader.cjs +1 -0
  15. package/dist/handy-uploader.css +1 -1
  16. package/dist/handy-uploader.mjs +1110 -0
  17. package/dist/language-CYpPw-mk.mjs +551 -0
  18. package/dist/language-fvWXvWRx.js +1 -0
  19. package/dist/lib/index.d.ts +8 -19
  20. package/dist/lib/language.d.ts +3 -0
  21. package/dist/lib/shared.d.ts +5 -0
  22. package/dist/lib/vuetify.d.ts +15 -0
  23. package/dist/types/index.d.ts +4 -0
  24. package/dist/utils/fileUtils.d.ts +1 -56
  25. package/dist/vue/components/HandyDialog.vue.d.ts +31 -0
  26. package/dist/vue/components/HandyDropzone.vue.d.ts +38 -0
  27. package/dist/vue/components/HandyFileIcon.vue.d.ts +9 -0
  28. package/dist/vue/components/HandyFileList.vue.d.ts +65 -0
  29. package/dist/vue/components/HandyIcon.vue.d.ts +10 -0
  30. package/dist/vue/components/HandyUploader.vue.d.ts +137 -0
  31. package/dist/vue/index.d.ts +9 -0
  32. package/dist/vue/types.d.ts +5 -0
  33. package/dist/vue/useUploader.d.ts +46 -0
  34. package/dist/vuetify.cjs +1 -0
  35. package/dist/vuetify.mjs +1875 -0
  36. package/package.json +59 -16
  37. package/dist/handy-uploader.es.js +0 -2308
  38. package/dist/handy-uploader.umd.js +0 -1
@@ -31,6 +31,7 @@ interface Props {
31
31
  tile?: boolean;
32
32
  }
33
33
  declare const __VLS_export: import("vue").DefineComponent<Props, {}, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
34
+ updateDocumentAttachment: (...args: any[]) => void;
34
35
  updateCardType: (...args: any[]) => void;
35
36
  updateBadgeCounter: (...args: any[]) => void;
36
37
  updateMaxFileCount: (...args: any[]) => void;
@@ -45,8 +46,8 @@ declare const __VLS_export: import("vue").DefineComponent<Props, {}, {}, {}, {},
45
46
  updateTableFixedHeader: (...args: any[]) => void;
46
47
  updateTableHeight: (...args: any[]) => void;
47
48
  updateLang: (...args: any[]) => void;
48
- updateDocumentAttachment: (...args: any[]) => void;
49
49
  }, string, import("vue").PublicProps, Readonly<Props> & Readonly<{
50
+ onUpdateDocumentAttachment?: (...args: any[]) => any;
50
51
  onUpdateCardType?: (...args: any[]) => any;
51
52
  onUpdateBadgeCounter?: (...args: any[]) => any;
52
53
  onUpdateMaxFileCount?: (...args: any[]) => any;
@@ -61,7 +62,6 @@ declare const __VLS_export: import("vue").DefineComponent<Props, {}, {}, {}, {},
61
62
  onUpdateTableFixedHeader?: (...args: any[]) => any;
62
63
  onUpdateTableHeight?: (...args: any[]) => any;
63
64
  onUpdateLang?: (...args: any[]) => any;
64
- onUpdateDocumentAttachment?: (...args: any[]) => any;
65
65
  }>, {
66
66
  maxFileSize: number;
67
67
  fileUploaderType: FileUploaderType;
@@ -75,7 +75,7 @@ declare const __VLS_export: import("vue").DefineComponent<Props, {}, {}, {}, {},
75
75
  changeFileName: boolean;
76
76
  addFileDescription: boolean;
77
77
  addFileTag: boolean;
78
- customLang: LanguageCollection | null;
78
+ customLang: LanguageCollection;
79
79
  insertPermission: boolean;
80
80
  lang: LanguageCode;
81
81
  thumb: boolean;
@@ -0,0 +1,2 @@
1
+ /** Logs a deprecation warning once per page load. */
2
+ export declare function warnDeprecated(name: string, replacement: string): void;
@@ -14,6 +14,10 @@ export interface ErrorHandlerOptions {
14
14
  autoRemoveTimeout?: number;
15
15
  logToConsole?: boolean;
16
16
  }
17
+ /**
18
+ * @deprecated Use the `errors` returned by `useUploader` (or the `error` event of
19
+ * HandyUploader) instead. `useErrorHandler` will be removed in the next major version.
20
+ */
17
21
  export declare function useErrorHandler(options?: ErrorHandlerOptions): {
18
22
  errors: unknown;
19
23
  isLoading: unknown;
@@ -7,6 +7,11 @@ export interface UseFileUploadOptions {
7
7
  imageCompressLevel?: number;
8
8
  fileAccept?: string;
9
9
  }
10
+ /**
11
+ * @deprecated Use `useUploader` from 'handy-uploader' instead: it validates before reading,
12
+ * supports drag and drop, image compression and editing files before they are added.
13
+ * `useFileUpload` will be removed in the next major version.
14
+ */
10
15
  export declare function useFileUpload(documentAttachment: Ref<DocumentAttachment[]>, options?: UseFileUploadOptions): {
11
16
  isUploading: Readonly<Ref<boolean, boolean>>;
12
17
  snackbar: Readonly<Ref<SnackbarConfig | {
@@ -0,0 +1,91 @@
1
+ import type { DocumentAttachment } from '../types';
2
+ /**
3
+ * Framework-agnostic attachment pipeline: read selected files, then validate and
4
+ * prepare them for the attachment list. Nothing here touches Vue, Vuetify or i18n —
5
+ * errors come back as codes so each UI layer can render its own messages.
6
+ */
7
+ export type AttachmentErrorCode = 'maxFileCount' | 'maxFileSize' | 'invalidFormat' | 'fileType';
8
+ export interface AttachmentError {
9
+ code: AttachmentErrorCode;
10
+ fileName?: string;
11
+ limit?: number;
12
+ }
13
+ export interface PrepareOptions {
14
+ /** Number of attachments already in the list. */
15
+ currentCount: number;
16
+ maxFileCount: number;
17
+ /** Maximum size per file, in bytes. */
18
+ maxFileSize: number;
19
+ imageCompressor?: boolean;
20
+ /** JPEG quality between 0 and 1. */
21
+ imageCompressLevel?: number;
22
+ }
23
+ export interface PrepareResult {
24
+ accepted: DocumentAttachment[];
25
+ errors: AttachmentError[];
26
+ }
27
+ export type CompressFn = (dataUrl: string, quality: number) => Promise<string>;
28
+ /** Extensions that imageCompressor re-encodes as JPEG. */
29
+ export declare const COMPRESSIBLE_EXTENSIONS: string[];
30
+ /** Splits "my.report.pdf" into { name: "my.report", format: "pdf" }. */
31
+ export declare function splitFileName(fileName: string): {
32
+ name: string;
33
+ format: string;
34
+ };
35
+ /** Joins a base name and extension back together ("README" stays "README"). */
36
+ export declare function joinFileName(name: string, format: string): string;
37
+ /** Size in bytes of the data a base64 string decodes to. */
38
+ export declare function base64ByteLength(base64: string): number;
39
+ /**
40
+ * Checks a file against an `accept` string in the same format as the HTML attribute
41
+ * (".pdf,image/*,application/zip"). An empty string or "*" accepts everything.
42
+ */
43
+ export declare function matchesAccept(file: {
44
+ name: string;
45
+ type?: string;
46
+ }, accept?: string): boolean;
47
+ /** Splits files into those matching `accept` and a `fileType` error for each other one. */
48
+ export declare function filterByAccept(files: File[], accept?: string): {
49
+ accepted: File[];
50
+ errors: AttachmentError[];
51
+ };
52
+ export interface PrecheckOptions {
53
+ currentCount: number;
54
+ maxFileCount: number;
55
+ /** Maximum size per file, in bytes. */
56
+ maxFileSize: number;
57
+ }
58
+ /**
59
+ * Applies the count and size limits using File metadata only, before any file is read,
60
+ * so oversized or surplus files never get loaded into memory.
61
+ */
62
+ export declare function precheckFiles(files: File[], { currentCount, maxFileCount, maxFileSize }: PrecheckOptions): {
63
+ accepted: File[];
64
+ errors: AttachmentError[];
65
+ };
66
+ /** Formats a byte count as "12.3 KB" / "4.5 MB", with translatable unit labels. */
67
+ export declare function formatBytes(bytes: number, units?: {
68
+ kb: string;
69
+ mb: string;
70
+ }): string;
71
+ /** Reads a Blob as a data URL. */
72
+ export declare function readFileAsDataUrl(file: Blob): Promise<string>;
73
+ /**
74
+ * Turns selected files into staged attachments (base name, extension as format, raw
75
+ * base64, size in bytes). Files that cannot be read are skipped.
76
+ */
77
+ export declare function readFiles(files: File[]): Promise<DocumentAttachment[]>;
78
+ /**
79
+ * Re-encodes an image data URL as JPEG at the given quality (0–1). Transparent areas
80
+ * are filled with white, since JPEG has no alpha channel. Browser only.
81
+ */
82
+ export declare function compressDataUrl(dataUrl: string, quality: number): Promise<string>;
83
+ /**
84
+ * Validates staged attachments against the limits and converts them to the shape that
85
+ * is stored in the attachment list. Stops at the file-count limit; skips files that are
86
+ * too large or cannot be processed.
87
+ *
88
+ * With imageCompressor on, JPEG/PNG/WebP images are re-encoded as JPEG; the result is
89
+ * kept only if it is smaller, in which case the stored format becomes "jpg".
90
+ */
91
+ export declare function prepareAttachments(staged: DocumentAttachment[], options: PrepareOptions, compress?: CompressFn): Promise<PrepareResult>;
@@ -0,0 +1,56 @@
1
+ import type { FileSizeResult, FileIconProps, MimeType } from '../types';
2
+ /**
3
+ * Formats file size into human-readable format with appropriate color coding
4
+ */
5
+ export declare function formatFileSize(size: number): FileSizeResult;
6
+ /**
7
+ * Determines file type based on file extension or MIME type
8
+ */
9
+ export declare function getFileType(fileName: string, mimeType?: string): string;
10
+ /**
11
+ * Gets appropriate icon and color for file type (legacy function for backward compatibility)
12
+ */
13
+ export declare function getFileIcon(fileName: string, mimeType?: string): FileIconProps;
14
+ /**
15
+ * Gets detailed icon and color for specific file extension
16
+ */
17
+ export declare function getDetailedFileIcon(fileName: string): {
18
+ icon: string;
19
+ color: string;
20
+ };
21
+ /**
22
+ * Gets only the icon name for a file extension
23
+ */
24
+ export declare function getFileIconName(fileName: string): string;
25
+ /**
26
+ * Gets only the color for a file extension
27
+ */
28
+ export declare function getFileIconColor(fileName: string): string;
29
+ /**
30
+ * Checks if file is an image type
31
+ */
32
+ export declare function isImageFile(fileName: string, mimeType?: string): boolean;
33
+ /**
34
+ * Validates file size against maximum allowed size
35
+ */
36
+ export declare function validateFileSize(fileSize: number, maxSize: number): boolean;
37
+ /**
38
+ * Validates file count against maximum allowed count
39
+ */
40
+ export declare function validateFileCount(currentCount: number, maxCount: number): boolean;
41
+ /**
42
+ * Gets MIME type from file extension
43
+ */
44
+ export declare function getMimeTypeFromExtension(fileName: string): MimeType;
45
+ /**
46
+ * Constructs proper data URL for base64 image data
47
+ */
48
+ export declare function constructImageDataUrl(base64: string | undefined, format: string | undefined): string;
49
+ /**
50
+ * Compresses image using canvas
51
+ */
52
+ export declare function compressImage(file: File, quality?: number, maxWidth?: number, maxHeight?: number): Promise<string>;
53
+ /**
54
+ * Converts file to base64 string
55
+ */
56
+ export declare function fileToBase64(file: File): Promise<string>;
@@ -0,0 +1,3 @@
1
+ export * from './fileUtils';
2
+ export * from './attachments';
3
+ export * from './videoThumbnail';
@@ -0,0 +1,32 @@
1
+ import type { FileData } from '../types';
2
+ type VideoSource = Pick<FileData, 'name' | 'format' | 'base64'>;
3
+ /** Builds a playable data URL for a stored video attachment. */
4
+ export declare function getVideoDataUrl(file: VideoSource): string;
5
+ /**
6
+ * Captures a frame (at 1s or 10% of the duration, whichever is earlier) and returns
7
+ * it as a JPEG data URL. Browser only.
8
+ */
9
+ export declare function generateVideoThumbnail(file: VideoSource): Promise<string>;
10
+ export interface VideoThumbnailCache {
11
+ /** Returns the cached thumbnail, or starts generating it and returns undefined. */
12
+ get(file: VideoSource): string | undefined;
13
+ /**
14
+ * Drops a cached thumbnail (e.g. its <img> failed to load) and notifies, so the UI
15
+ * re-renders and the next get() regenerates it. After one retry the file is given up on.
16
+ */
17
+ invalidate(file: VideoSource): void;
18
+ /** Frees thumbnails of files that are no longer shown. */
19
+ retain(files: VideoSource[]): void;
20
+ }
21
+ /**
22
+ * Key from name, total length and the end of the data. The first bytes of a video are
23
+ * the container header, which is often identical across clips from the same device.
24
+ */
25
+ export declare function videoThumbnailKey(file: VideoSource): string;
26
+ /**
27
+ * Caches generated thumbnails and de-duplicates in-flight work. `onUpdate` fires when a
28
+ * thumbnail becomes available or is invalidated, so a UI layer can re-render (bump a Vue
29
+ * ref, set React state, …). Failed generations are retried once, then given up on.
30
+ */
31
+ export declare function createVideoThumbnailCache(onUpdate: () => void, generate?: (file: VideoSource) => Promise<string>): VideoThumbnailCache;
32
+ export {};
@@ -0,0 +1,20 @@
1
+ import { type PropType } from 'vue';
2
+ import type { DocumentAttachment } from '../types';
3
+ declare const _default: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
4
+ /** The file list. Set it as a JS property (`el.files = [...]`); read it back the same way. */
5
+ files: {
6
+ type: PropType<DocumentAttachment[]>;
7
+ default: any;
8
+ };
9
+ }>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
10
+ [key: string]: any;
11
+ }>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
12
+ /** The file list. Set it as a JS property (`el.files = [...]`); read it back the same way. */
13
+ files: {
14
+ type: PropType<DocumentAttachment[]>;
15
+ default: any;
16
+ };
17
+ }>> & Readonly<{}>, {
18
+ files: DocumentAttachment[];
19
+ }, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;
20
+ export default _default;
@@ -0,0 +1,21 @@
1
+ import type { HandyUploaderElement as HandyUploaderElementType, HandyUploaderElementConstructor } from './types';
2
+ export type { HandyUploaderElementProps, HandyUploaderElementConstructor, HandyUploaderChangeDetail, HandyUploaderAddDetail, HandyUploaderRemoveDetail, HandyUploaderErrorDetail, HandyUploaderEventMap } from './types';
3
+ export type { DocumentAttachment, FileData, LanguageCollection } from '../types';
4
+ export type { AttachmentError } from '../core';
5
+ /** The custom element class behind <handy-uploader>. */
6
+ export declare const HandyUploaderElement: HandyUploaderElementConstructor;
7
+ export type HandyUploaderElement = HandyUploaderElementType;
8
+ /** Adds the default theme to the page once. Called automatically when the element is defined. */
9
+ export declare function injectStyles(doc?: Document): void;
10
+ /**
11
+ * Registers the element under `tagName` (default `handy-uploader`). Safe to call more than
12
+ * once. Pass `{ styles: false }` to skip the default theme.
13
+ */
14
+ export declare function defineHandyUploader(tagName?: string, { styles }?: {
15
+ styles?: boolean;
16
+ }): void;
17
+ declare global {
18
+ interface HTMLElementTagNameMap {
19
+ 'handy-uploader': HandyUploaderElementType;
20
+ }
21
+ }
@@ -0,0 +1,108 @@
1
+ import type { CardType, DocumentAttachment, LanguageCollection } from '../types';
2
+ import type { AttachmentError } from '../core';
3
+ /**
4
+ * Properties of the <handy-uploader> element. Each one can also be set as a kebab-case
5
+ * attribute.
6
+ */
7
+ export interface HandyUploaderElementProps {
8
+ /** The file list. Set and read it as a JS property: `el.files = [...]`. */
9
+ files: DocumentAttachment[];
10
+ /** Layout. Attribute: `file-uploader-type`. Default `'thumbnail'`. */
11
+ fileUploaderType?: 'thumbnail' | 'simple' | 'table';
12
+ /** Maximum size per file, in bytes. Attribute: `max-file-size`. Default 5242880 (5 MB). */
13
+ maxFileSize?: number;
14
+ /** Maximum number of files. Attribute: `max-file-count`. Default 10. */
15
+ maxFileCount?: number;
16
+ /** Accepted types, HTML accept format (".pdf,image/*"). Attribute: `file-accept`. */
17
+ fileAccept?: string;
18
+ /** Compress JPEG/PNG/WebP images. Attribute: `image-compressor`. */
19
+ imageCompressor?: boolean;
20
+ /** JPEG quality 0–1. Attribute: `image-compress-level`. Default 0.8. */
21
+ imageCompressLevel?: number;
22
+ /** Show image previews and video thumbnails. Attribute: `thumb`. Default true. */
23
+ thumb?: boolean;
24
+ /** Thumbnail view: card width out of 12 columns. Attribute: `cols`. Default 3. */
25
+ cols?: number;
26
+ /** Card style. Attribute: `card-type`. */
27
+ cardType?: CardType;
28
+ /** Show the file count on the Insert button. Attribute: `badge-counter`. Default true. */
29
+ badgeCounter?: boolean;
30
+ /** Button colour: a Vuetify colour name or any CSS colour. Attribute: `btn-color`. */
31
+ btnColor?: string;
32
+ /** Let users rename files. Attribute: `change-file-name`. */
33
+ changeFileName?: boolean;
34
+ /** Let users add a description. Attribute: `add-file-description`. */
35
+ addFileDescription?: boolean;
36
+ /** Let users pick tags from `tags`. Attribute: `add-file-tag`. */
37
+ addFileTag?: boolean;
38
+ /** Tags to choose from. Attribute: `tags="invoice, contract"` (comma-separated). */
39
+ tags?: string[];
40
+ /** Show the Insert button. Attribute: `insert-permission`. Default true. */
41
+ insertPermission?: boolean;
42
+ /** Show the edit button. Attribute: `edit-permission`. Default true. */
43
+ editPermission?: boolean;
44
+ /** Show the delete button. Attribute: `delete-permission`. Default true. */
45
+ deletePermission?: boolean;
46
+ /** Table view: show the preview column. Attribute: `table-thumb-column`. Default true. */
47
+ tableThumbColumn?: boolean;
48
+ /** Table view: sticky header. Attribute: `table-fixed-header`. Default true. */
49
+ tableFixedHeader?: boolean;
50
+ /** Table view: height in pixels. Attribute: `table-height`. Default 400. */
51
+ tableHeight?: number;
52
+ /** Language: en, fa, fr, ch, ar, or a key from `customLang`. Attribute: `lang`. */
53
+ lang?: string;
54
+ /** Your own translations (JS property only). */
55
+ customLang?: LanguageCollection | null;
56
+ /** Right-to-left layout (automatic for fa and ar). Attribute: `rtl-support`. */
57
+ rtlSupport?: boolean;
58
+ }
59
+ type Listener<E> = (this: HandyUploaderElement, event: E) => unknown;
60
+ /** The <handy-uploader> element. */
61
+ export interface HandyUploaderElement extends HTMLElement, Omit<HandyUploaderElementProps, 'lang'> {
62
+ /** Language: en, fa, fr, ch, ar, or a key from `customLang`. */
63
+ lang: string;
64
+ /** Validate, read and add files (e.g. from your own drop zone). Resolves with what was added. */
65
+ addFiles(files: FileList | File[]): Promise<DocumentAttachment[]>;
66
+ /** Remove a file by index, without the confirmation dialog. */
67
+ removeAt(index: number): void;
68
+ /** Open the insert dialog. */
69
+ openInsert(): void;
70
+ addEventListener<K extends keyof HandyUploaderEventMap>(type: K, listener: Listener<HandyUploaderEventMap[K]>, options?: boolean | AddEventListenerOptions): void;
71
+ addEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: Listener<HTMLElementEventMap[K]>, options?: boolean | AddEventListenerOptions): void;
72
+ addEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions): void;
73
+ removeEventListener<K extends keyof HandyUploaderEventMap>(type: K, listener: Listener<HandyUploaderEventMap[K]>, options?: boolean | EventListenerOptions): void;
74
+ removeEventListener<K extends keyof HTMLElementEventMap>(type: K, listener: Listener<HTMLElementEventMap[K]>, options?: boolean | EventListenerOptions): void;
75
+ removeEventListener(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | EventListenerOptions): void;
76
+ }
77
+ export interface HandyUploaderElementConstructor {
78
+ new (): HandyUploaderElement;
79
+ prototype: HandyUploaderElement;
80
+ }
81
+ /** `hu-change`: the file list changed (added, edited or removed). */
82
+ export interface HandyUploaderChangeDetail {
83
+ files: DocumentAttachment[];
84
+ }
85
+ /** `hu-add`: files were added. */
86
+ export interface HandyUploaderAddDetail {
87
+ added: DocumentAttachment[];
88
+ }
89
+ /** `hu-remove`: a file was removed. */
90
+ export interface HandyUploaderRemoveDetail {
91
+ attachment: DocumentAttachment;
92
+ index: number;
93
+ }
94
+ /** `hu-error`: files were rejected. */
95
+ export interface HandyUploaderErrorDetail {
96
+ errors: AttachmentError[];
97
+ }
98
+ /**
99
+ * Events dispatched by <handy-uploader>. They are prefixed with `hu-` so they can't be confused
100
+ * with native `change`/`error` events bubbling up from the inputs inside the element.
101
+ */
102
+ export interface HandyUploaderEventMap {
103
+ 'hu-change': CustomEvent<HandyUploaderChangeDetail>;
104
+ 'hu-add': CustomEvent<HandyUploaderAddDetail>;
105
+ 'hu-remove': CustomEvent<HandyUploaderRemoveDetail>;
106
+ 'hu-error': CustomEvent<HandyUploaderErrorDetail>;
107
+ }
108
+ export {};