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.
- package/README.md +290 -292
- package/dist/components/handyUploader.vue.d.ts +3 -3
- package/dist/composables/deprecation.d.ts +2 -0
- package/dist/composables/useErrorHandler.d.ts +4 -0
- package/dist/composables/useFileUpload.d.ts +5 -0
- package/dist/core/attachments.d.ts +91 -0
- package/dist/core/fileUtils.d.ts +56 -0
- package/dist/core/index.d.ts +3 -0
- package/dist/core/videoThumbnail.d.ts +32 -0
- package/dist/element/HandyUploaderElement.d.ts +20 -0
- package/dist/element/index.d.ts +21 -0
- package/dist/element/types.d.ts +108 -0
- package/dist/element.mjs +6178 -0
- package/dist/handy-uploader.cjs +1 -0
- package/dist/handy-uploader.css +1 -1
- package/dist/handy-uploader.mjs +1110 -0
- package/dist/language-CYpPw-mk.mjs +551 -0
- package/dist/language-fvWXvWRx.js +1 -0
- package/dist/lib/index.d.ts +8 -19
- package/dist/lib/language.d.ts +3 -0
- package/dist/lib/shared.d.ts +5 -0
- package/dist/lib/vuetify.d.ts +15 -0
- package/dist/types/index.d.ts +4 -0
- package/dist/utils/fileUtils.d.ts +1 -56
- package/dist/vue/components/HandyDialog.vue.d.ts +31 -0
- package/dist/vue/components/HandyDropzone.vue.d.ts +38 -0
- package/dist/vue/components/HandyFileIcon.vue.d.ts +9 -0
- package/dist/vue/components/HandyFileList.vue.d.ts +65 -0
- package/dist/vue/components/HandyIcon.vue.d.ts +10 -0
- package/dist/vue/components/HandyUploader.vue.d.ts +137 -0
- package/dist/vue/index.d.ts +9 -0
- package/dist/vue/types.d.ts +5 -0
- package/dist/vue/useUploader.d.ts +46 -0
- package/dist/vuetify.cjs +1 -0
- package/dist/vuetify.mjs +1875 -0
- package/package.json +59 -16
- package/dist/handy-uploader.es.js +0 -2308
- package/dist/handy-uploader.umd.js +0 -1
package/README.md
CHANGED
|
@@ -3,38 +3,31 @@
|
|
|
3
3
|
[](https://badge.fury.io/js/handy-uploader)
|
|
4
4
|
[](https://opensource.org/licenses/MIT)
|
|
5
5
|
[](https://vuejs.org/)
|
|
6
|
+
[](#web-component-react-svelte-angular-plain-html)
|
|
6
7
|
[](https://www.typescriptlang.org/)
|
|
7
8
|
|
|
8
|
-
## 🚀 [Live Demo](https://
|
|
9
|
+
## 🚀 [Live Demo](https://alijahanpak.github.io/handy-uploader/)
|
|
9
10
|
|
|
10
|
-
A
|
|
11
|
+
A file uploader for **Vue, React, Svelte, Angular and plain HTML**, with **automatic video thumbnails**, **image compression**, three layouts (thumbnail, simple, table), per-file names, descriptions and tags, and translations for 5 languages.
|
|
11
12
|
|
|
12
|
-
|
|
13
|
+
It comes in three flavours with **the same options**:
|
|
13
14
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
-
|
|
17
|
-
|
|
18
|
-
-
|
|
15
|
+
| Import | Use it in | Needs | Styling |
|
|
16
|
+
| --- | --- | --- | --- |
|
|
17
|
+
| `handy-uploader` | Vue 3 | Vue 3 | Plain CSS, works with any CSS framework (Tailwind, Bootstrap, your own) |
|
|
18
|
+
| `handy-uploader/vuetify` | Vue 3 + Vuetify | Vue 3 + Vuetify 3 | Vuetify components |
|
|
19
|
+
| `handy-uploader/element` | React, Svelte, Angular, plain HTML, any framework | Nothing (self-contained) | Same plain CSS, injected automatically |
|
|
19
20
|
|
|
20
|
-
|
|
21
|
-
- **Images**: JPG, JPEG, PNG, GIF, BMP, SVG, WebP, TIFF
|
|
22
|
-
- **Videos**: MP4, AVI, MOV, WMV, FLV, WebM
|
|
23
|
-
- **Documents**: PDF, DOC, DOCX, TXT, RTF, ODT
|
|
24
|
-
- **Spreadsheets**: XLS, XLSX, CSV, ODS
|
|
25
|
-
- **Presentations**: PPT, PPTX, ODP
|
|
26
|
-
- **Archives**: ZIP, RAR, 7Z, TAR, GZ
|
|
27
|
-
- **Audio**: MP3, WAV, FLAC, AAC, OGG
|
|
21
|
+
## ✨ Features
|
|
28
22
|
|
|
29
|
-
|
|
30
|
-
- **
|
|
31
|
-
- **
|
|
32
|
-
- **
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
- **
|
|
36
|
-
-
|
|
37
|
-
- Easy language switching
|
|
23
|
+
- **Video thumbnails:** a frame is captured automatically for MP4, WebM, MOV and other formats the browser can play.
|
|
24
|
+
- **Image compression:** optional; JPEG, PNG and WebP are re-encoded as JPEG, and the smaller result is kept.
|
|
25
|
+
- **Three views:** `thumbnail` (preview cards), `simple` (compact cards) and `table`.
|
|
26
|
+
- **File details:** rename files, and add descriptions and tags before or after upload.
|
|
27
|
+
- **Validation:** file size, file count and accepted types, including for drag-and-dropped files.
|
|
28
|
+
- **Permissions:** turn insert, edit and delete on or off.
|
|
29
|
+
- **Languages:** English, Persian, French, Chinese and Arabic, with right-to-left layout for Persian and Arabic. You can also add your own translations.
|
|
30
|
+
- **TypeScript:** full type declarations.
|
|
38
31
|
|
|
39
32
|
## 📦 Installation
|
|
40
33
|
|
|
@@ -42,362 +35,367 @@ A comprehensive Vue 3 file uploader component library with advanced features inc
|
|
|
42
35
|
npm install handy-uploader
|
|
43
36
|
```
|
|
44
37
|
|
|
45
|
-
|
|
46
|
-
yarn add handy-uploader
|
|
47
|
-
```
|
|
48
|
-
|
|
49
|
-
```bash
|
|
50
|
-
pnpm add handy-uploader
|
|
51
|
-
```
|
|
38
|
+
For the Vuetify flavour, also install `vuetify@^3` (and `@mdi/font` for its icons). The Web Component needs nothing else: Vue is bundled inside it.
|
|
52
39
|
|
|
53
40
|
## 🚀 Quick Start
|
|
54
41
|
|
|
55
|
-
###
|
|
56
|
-
|
|
57
|
-
Make sure you have the required peer dependencies:
|
|
58
|
-
|
|
59
|
-
```bash
|
|
60
|
-
npm install vue@^3.0.0 vuetify@^3.0.0
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
### 2. Import and Use
|
|
42
|
+
### Without Vuetify (any CSS framework)
|
|
64
43
|
|
|
65
44
|
```vue
|
|
66
|
-
<template>
|
|
67
|
-
<div>
|
|
68
|
-
<!-- Thumbnail Uploader with Video Support -->
|
|
69
|
-
<ThumbnailUploader
|
|
70
|
-
:max-file-size="10485760"
|
|
71
|
-
:max-file-count="5"
|
|
72
|
-
:accepted-file-types="['image/*', 'video/*']"
|
|
73
|
-
:language="'en'"
|
|
74
|
-
@files-selected="handleFilesSelected"
|
|
75
|
-
/>
|
|
76
|
-
</div>
|
|
77
|
-
</template>
|
|
78
|
-
|
|
79
45
|
<script setup lang="ts">
|
|
80
|
-
import {
|
|
81
|
-
import type
|
|
46
|
+
import { ref } from 'vue'
|
|
47
|
+
import { HandyUploader, type DocumentAttachment } from 'handy-uploader'
|
|
48
|
+
import 'handy-uploader/style.css'
|
|
82
49
|
|
|
83
|
-
const
|
|
84
|
-
console.log('Selected files:', files)
|
|
85
|
-
// Each file includes base64 data and video thumbnails are auto-generated
|
|
86
|
-
}
|
|
50
|
+
const files = ref<DocumentAttachment[]>([])
|
|
87
51
|
</script>
|
|
52
|
+
|
|
53
|
+
<template>
|
|
54
|
+
<HandyUploader
|
|
55
|
+
v-model:document-attachment="files"
|
|
56
|
+
file-uploader-type="thumbnail"
|
|
57
|
+
file-accept="image/*,video/*,.pdf"
|
|
58
|
+
:max-file-size="10 * 1024 * 1024"
|
|
59
|
+
:max-file-count="10"
|
|
60
|
+
change-file-name
|
|
61
|
+
add-file-description
|
|
62
|
+
add-file-tag
|
|
63
|
+
:tags="['invoice', 'contract', 'photo']"
|
|
64
|
+
/>
|
|
65
|
+
</template>
|
|
88
66
|
```
|
|
89
67
|
|
|
90
|
-
###
|
|
68
|
+
### With Vuetify
|
|
91
69
|
|
|
92
|
-
```
|
|
70
|
+
```ts
|
|
93
71
|
// main.ts
|
|
94
72
|
import { createApp } from 'vue'
|
|
95
73
|
import { createVuetify } from 'vuetify'
|
|
96
74
|
import 'vuetify/styles'
|
|
97
75
|
import '@mdi/font/css/materialdesignicons.css'
|
|
76
|
+
import App from './App.vue'
|
|
98
77
|
|
|
99
|
-
|
|
100
|
-
const app = createApp(App)
|
|
101
|
-
|
|
102
|
-
app.use(vuetify)
|
|
103
|
-
app.mount('#app')
|
|
78
|
+
createApp(App).use(createVuetify()).mount('#app')
|
|
104
79
|
```
|
|
105
80
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
81
|
+
```vue
|
|
82
|
+
<script setup lang="ts">
|
|
83
|
+
import { ref } from 'vue'
|
|
84
|
+
import { HandyUploader } from 'handy-uploader/vuetify'
|
|
85
|
+
import type { DocumentAttachment } from 'handy-uploader/vuetify'
|
|
109
86
|
|
|
110
|
-
|
|
87
|
+
const files = ref<DocumentAttachment[]>([])
|
|
88
|
+
</script>
|
|
111
89
|
|
|
112
|
-
```vue
|
|
113
90
|
<template>
|
|
114
|
-
<
|
|
115
|
-
:max-file-size="52428800"
|
|
116
|
-
:max-file-count="10"
|
|
117
|
-
:accepted-file-types="['image/*', 'video/*', 'application/pdf']"
|
|
118
|
-
:language="'en'"
|
|
119
|
-
:theme="'light'"
|
|
120
|
-
@files-selected="onFilesSelected"
|
|
121
|
-
@file-removed="onFileRemoved"
|
|
122
|
-
@error="onError"
|
|
123
|
-
/>
|
|
91
|
+
<HandyUploader v-model:document-attachment="files" file-uploader-type="table" />
|
|
124
92
|
</template>
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
Switching between the two is a one-line change, because the props are the same.
|
|
125
96
|
|
|
126
|
-
|
|
127
|
-
import { ThumbnailUploader } from 'handy-uploader'
|
|
97
|
+
### Web Component (React, Svelte, Angular, plain HTML)
|
|
128
98
|
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
99
|
+
Importing `handy-uploader/element` registers a `<handy-uploader>` element and adds the default theme to the page. Three rules cover every framework:
|
|
100
|
+
|
|
101
|
+
- **Options are attributes** in kebab-case: `max-file-count="5"`, `change-file-name`, `tags="invoice, contract"`. Booleans accept `"false"`.
|
|
102
|
+
- **The file list is the `files` property** (an array), not an attribute.
|
|
103
|
+
- **Changes come as DOM events** prefixed with `hu-`: `hu-change` (`event.detail.files`), `hu-add`, `hu-remove` and `hu-error`.
|
|
104
|
+
|
|
105
|
+
**React 19**
|
|
106
|
+
|
|
107
|
+
```tsx
|
|
108
|
+
import { useState } from 'react'
|
|
109
|
+
import 'handy-uploader/element'
|
|
110
|
+
import type { DocumentAttachment } from 'handy-uploader/element'
|
|
111
|
+
|
|
112
|
+
export default function App() {
|
|
113
|
+
const [files, setFiles] = useState<DocumentAttachment[]>([])
|
|
114
|
+
return (
|
|
115
|
+
<handy-uploader
|
|
116
|
+
files={files}
|
|
117
|
+
max-file-count={5}
|
|
118
|
+
change-file-name
|
|
119
|
+
tags="invoice, contract"
|
|
120
|
+
onhu-change={(event) => setFiles(event.detail.files)}
|
|
121
|
+
/>
|
|
122
|
+
)
|
|
136
123
|
}
|
|
137
|
-
</script>
|
|
138
124
|
```
|
|
139
125
|
|
|
140
|
-
|
|
126
|
+
For TypeScript, declare the element in JSX once; see [examples/react-19/src/handy-uploader.d.ts](examples/react-19/src/handy-uploader.d.ts).
|
|
127
|
+
|
|
128
|
+
**React 18** doesn't pass properties or custom events to custom elements, so use a ref:
|
|
129
|
+
|
|
130
|
+
```tsx
|
|
131
|
+
const ref = useRef<HandyUploaderElement>(null)
|
|
132
|
+
useEffect(() => {
|
|
133
|
+
if (ref.current) ref.current.files = files
|
|
134
|
+
}, [files])
|
|
135
|
+
useEffect(() => {
|
|
136
|
+
const el = ref.current!
|
|
137
|
+
const onChange = (event: CustomEvent<HandyUploaderChangeDetail>) => setFiles(event.detail.files)
|
|
138
|
+
el.addEventListener('hu-change', onChange)
|
|
139
|
+
return () => el.removeEventListener('hu-change', onChange)
|
|
140
|
+
}, [])
|
|
141
|
+
// <handy-uploader ref={ref} max-file-count={5} />
|
|
142
|
+
```
|
|
141
143
|
|
|
142
|
-
|
|
144
|
+
**Svelte 5**
|
|
143
145
|
|
|
144
|
-
```
|
|
145
|
-
<
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
146
|
+
```svelte
|
|
147
|
+
<script>
|
|
148
|
+
import 'handy-uploader/element'
|
|
149
|
+
let files = $state.raw([])
|
|
150
|
+
</script>
|
|
151
|
+
|
|
152
|
+
<handy-uploader
|
|
153
|
+
files={files}
|
|
154
|
+
max-file-count="5"
|
|
155
|
+
onhu-change={(event) => (files = event.detail.files)}
|
|
156
|
+
></handy-uploader>
|
|
153
157
|
```
|
|
154
158
|
|
|
155
|
-
|
|
159
|
+
**Angular** (standalone component)
|
|
160
|
+
|
|
161
|
+
```ts
|
|
162
|
+
import { CUSTOM_ELEMENTS_SCHEMA, Component, signal } from '@angular/core'
|
|
163
|
+
import 'handy-uploader/element'
|
|
164
|
+
import type { DocumentAttachment, HandyUploaderChangeDetail } from 'handy-uploader/element'
|
|
165
|
+
|
|
166
|
+
@Component({
|
|
167
|
+
selector: 'app-root',
|
|
168
|
+
schemas: [CUSTOM_ELEMENTS_SCHEMA],
|
|
169
|
+
template: `<handy-uploader
|
|
170
|
+
[files]="files()"
|
|
171
|
+
max-file-count="5"
|
|
172
|
+
(hu-change)="onChange($event)"
|
|
173
|
+
></handy-uploader>`
|
|
174
|
+
})
|
|
175
|
+
export class AppComponent {
|
|
176
|
+
readonly files = signal<DocumentAttachment[]>([])
|
|
177
|
+
onChange(event: Event) {
|
|
178
|
+
this.files.set((event as CustomEvent<HandyUploaderChangeDetail>).detail.files)
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
```
|
|
156
182
|
|
|
157
|
-
|
|
183
|
+
**Plain HTML** (no build step)
|
|
158
184
|
|
|
159
|
-
```
|
|
160
|
-
<
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
185
|
+
```html
|
|
186
|
+
<handy-uploader id="uploader" max-file-count="5" change-file-name></handy-uploader>
|
|
187
|
+
|
|
188
|
+
<script type="module">
|
|
189
|
+
import 'https://cdn.jsdelivr.net/npm/handy-uploader@3/dist/element.mjs'
|
|
190
|
+
|
|
191
|
+
const el = document.getElementById('uploader')
|
|
192
|
+
el.files = []
|
|
193
|
+
el.addEventListener('hu-change', (event) => console.log(event.detail.files))
|
|
194
|
+
</script>
|
|
167
195
|
```
|
|
168
196
|
|
|
197
|
+
The element also has methods for your own drop zones or paste handling: `el.addFiles(files)` (validates and adds, resolves with what was added), `el.removeAt(index)` and `el.openInsert()`. Call them once the element is on the page. Use `defineHandyUploader('my-uploader', { styles: false })` to register it under another tag name or without the default theme.
|
|
198
|
+
|
|
199
|
+
Complete, tested apps for each framework are in [examples/](examples/).
|
|
200
|
+
|
|
201
|
+
## 🧭 Framework Support
|
|
202
|
+
|
|
203
|
+
| Framework | Use |
|
|
204
|
+
| --- | --- |
|
|
205
|
+
| **Vue 3** (any CSS) | ✅ `handy-uploader` |
|
|
206
|
+
| **Vue 3 + Vuetify 3** | ✅ `handy-uploader/vuetify` |
|
|
207
|
+
| **React 18 / 19** | ✅ `handy-uploader/element` |
|
|
208
|
+
| **Svelte 5** | ✅ `handy-uploader/element` |
|
|
209
|
+
| **Angular** | ✅ `handy-uploader/element` |
|
|
210
|
+
| **Plain HTML / any other framework** | ✅ `handy-uploader/element` |
|
|
211
|
+
|
|
212
|
+
Every one of these is covered by browser tests on each pull request. The upload logic (reading files, validation, compression, video thumbnails) lives in a framework-free core that is also exported; see [Building your own UI](#-building-your-own-ui).
|
|
213
|
+
|
|
214
|
+
## 📚 Documentation
|
|
215
|
+
|
|
216
|
+
The [live demo](https://alijahanpak.github.io/handy-uploader/) is a Storybook with guides and an interactive example of every feature:
|
|
217
|
+
|
|
218
|
+
- [Getting Started](https://alijahanpak.github.io/handy-uploader/?path=/docs/guide-getting-started--docs)
|
|
219
|
+
- [Feature Tour](https://alijahanpak.github.io/handy-uploader/?path=/docs/guide-feature-tour--docs): every feature, with a link to try it
|
|
220
|
+
- [Styling & Theming](https://alijahanpak.github.io/handy-uploader/?path=/docs/guide-styling-theming--docs)
|
|
221
|
+
- [Build Your Own UI](https://alijahanpak.github.io/handy-uploader/?path=/docs/guide-build-your-own-ui--docs)
|
|
222
|
+
- [Upgrading from 2.x](https://alijahanpak.github.io/handy-uploader/?path=/docs/guide-upgrading-from-2-x--docs)
|
|
223
|
+
- [Web Component](https://alijahanpak.github.io/handy-uploader/?path=/docs/web-component-handy-uploader--docs): `<handy-uploader>` with a live event log
|
|
224
|
+
|
|
169
225
|
## ⚙️ API Reference
|
|
170
226
|
|
|
171
|
-
###
|
|
227
|
+
### `HandyUploader` props
|
|
172
228
|
|
|
173
229
|
| Prop | Type | Default | Description |
|
|
174
|
-
|
|
175
|
-
| `
|
|
176
|
-
| `
|
|
177
|
-
| `
|
|
178
|
-
| `
|
|
179
|
-
| `
|
|
230
|
+
| --- | --- | --- | --- |
|
|
231
|
+
| `documentAttachment` | `DocumentAttachment[]` | `[]` | The files. Use with `v-model:document-attachment`, or pass an array. The component updates the array you pass in, as the Vuetify version always has. |
|
|
232
|
+
| `fileUploaderType` | `'thumbnail' \| 'simple' \| 'table'` | `'thumbnail'` | Layout. |
|
|
233
|
+
| `maxFileSize` | `number` | `5242880` | Maximum size per file, **in bytes** (5 MB). |
|
|
234
|
+
| `maxFileCount` | `number` | `10` | Maximum number of files. |
|
|
235
|
+
| `fileAccept` | `string` | `''` | Accepted types, in the same format as the HTML `accept` attribute, e.g. `"image/*,.pdf"`. Empty means everything. |
|
|
236
|
+
| `imageCompressor` | `boolean` | `false` | Compress JPEG, PNG and WebP images (re-encoded as JPEG, kept only when smaller). |
|
|
237
|
+
| `imageCompressLevel` | `number` | `0.8` | JPEG quality, from 0 to 1. |
|
|
238
|
+
| `thumb` | `boolean` | `true` | Show image previews and video thumbnails. When off, file-type icons are shown instead. |
|
|
239
|
+
| `cols` | `number` | `3` | Thumbnail view: card width out of 12 columns (3 = four per row, 4 = three per row). |
|
|
240
|
+
| `cardType` | `'default' \| 'outlined' \| 'raised' \| 'shaped' \| 'tile'` | `'default'` | Card style. |
|
|
241
|
+
| `badgeCounter` | `boolean` | `true` | Show the file count on the Insert button. |
|
|
242
|
+
| `btnColor` | `string` | `'info'` | Button colour: a Vuetify colour name (`primary`, `info`, `success`, …) or, without Vuetify, any CSS colour. |
|
|
243
|
+
| `changeFileName` | `boolean` | `false` | Let users rename files. |
|
|
244
|
+
| `addFileDescription` | `boolean` | `false` | Let users add a description. |
|
|
245
|
+
| `addFileTag` | `boolean` | `false` | Let users pick tags from `tags`. |
|
|
246
|
+
| `tags` | `string[]` | `[]` | Tags users can choose from. |
|
|
247
|
+
| `insertPermission` | `boolean` | `true` | Show the Insert button. |
|
|
248
|
+
| `editPermission` | `boolean` | `true` | Show the edit button. |
|
|
249
|
+
| `deletePermission` | `boolean` | `true` | Show the delete button. Deleting always asks for confirmation. |
|
|
250
|
+
| `tableThumbColumn` | `boolean` | `true` | Table view: show the preview column. |
|
|
251
|
+
| `tableFixedHeader` | `boolean` | `true` | Table view: keep the header visible while scrolling. |
|
|
252
|
+
| `tableHeight` | `number` | `400` | Table view: height in pixels when the header is fixed. |
|
|
253
|
+
| `lang` | `string` | `'en'` | Interface language: `en`, `fa`, `fr`, `ch`, `ar`, or a key you add with `customLang`. |
|
|
254
|
+
| `customLang` | `LanguageCollection \| null` | `null` | Your own translations (see [Internationalization](#-internationalization)). |
|
|
255
|
+
| `rtlSupport` | `boolean` | `false` | Right-to-left layout. Without Vuetify it is also turned on automatically for `fa` and `ar`. With Vuetify, use Vuetify's own RTL setting (`createVuetify({ locale: { rtl: … } })`). |
|
|
180
256
|
|
|
181
257
|
### Events
|
|
182
258
|
|
|
183
259
|
| Event | Payload | Description |
|
|
184
|
-
|
|
185
|
-
| `
|
|
186
|
-
| `
|
|
187
|
-
| `
|
|
260
|
+
| --- | --- | --- |
|
|
261
|
+
| `updateDocumentAttachment` | `DocumentAttachment[]` | The file list changed (added, edited or removed). |
|
|
262
|
+
| `update:documentAttachment` | `DocumentAttachment[]` | Same as above, for `v-model:document-attachment`. *(Not in the Vuetify flavour.)* |
|
|
263
|
+
| `add` | `DocumentAttachment[]` | Files were added. *(Not in the Vuetify flavour.)* |
|
|
264
|
+
| `remove` | `(attachment, index)` | A file was removed. *(Not in the Vuetify flavour.)* |
|
|
265
|
+
| `error` | `AttachmentError[]` | Files were rejected (`fileType`, `maxFileSize`, `maxFileCount`, `invalidFormat`). *(Not in the Vuetify flavour.)* |
|
|
188
266
|
|
|
189
|
-
|
|
267
|
+
When a prop changes, the component also emits a matching `update…` event (e.g. `updateCardType`, `updateLang`), as the 2.x versions did.
|
|
190
268
|
|
|
191
|
-
|
|
192
|
-
interface FileData {
|
|
193
|
-
id: string
|
|
194
|
-
name: string
|
|
195
|
-
size: number
|
|
196
|
-
type: string
|
|
197
|
-
format: string
|
|
198
|
-
base64?: string
|
|
199
|
-
thumbnail?: string // Auto-generated for videos
|
|
200
|
-
lastModified: number
|
|
201
|
-
}
|
|
202
|
-
```
|
|
203
|
-
|
|
204
|
-
## 🎯 Advanced Features
|
|
269
|
+
### Slots (without Vuetify)
|
|
205
270
|
|
|
206
|
-
|
|
271
|
+
| Slot | Props | Use |
|
|
272
|
+
| --- | --- | --- |
|
|
273
|
+
| `item` | `{ attachment, index, remove }` | Replace a whole card. |
|
|
274
|
+
| `actions` | `{ attachment, index }` | Add your own buttons to each card or row. |
|
|
275
|
+
| `empty` | – | Content to show when there are no files. |
|
|
207
276
|
|
|
208
|
-
|
|
277
|
+
### Data types
|
|
209
278
|
|
|
210
|
-
```
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
name: 'video.mp4',
|
|
214
|
-
type: 'video',
|
|
215
|
-
thumbnail: 'data:image/jpeg;base64,/9j/4AAQ...' // Auto-generated
|
|
279
|
+
```ts
|
|
280
|
+
interface DocumentAttachment {
|
|
281
|
+
file: FileData
|
|
216
282
|
}
|
|
217
|
-
```
|
|
218
|
-
|
|
219
|
-
### File Type Detection
|
|
220
|
-
|
|
221
|
-
Automatic file type detection and icon assignment:
|
|
222
283
|
|
|
223
|
-
|
|
224
|
-
//
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
284
|
+
interface FileData {
|
|
285
|
+
name: string // with extension, e.g. "report.pdf"
|
|
286
|
+
format: string // extension, e.g. "pdf"; "jpg" after compression
|
|
287
|
+
base64: string // file contents, without the "data:…;base64," prefix
|
|
288
|
+
size: number // bytes
|
|
289
|
+
tags: string[]
|
|
290
|
+
description: string | null
|
|
291
|
+
showDetailState: boolean
|
|
230
292
|
}
|
|
231
293
|
```
|
|
232
294
|
|
|
233
|
-
|
|
295
|
+
## 🎨 Styling (without Vuetify)
|
|
234
296
|
|
|
235
|
-
|
|
297
|
+
Import the default theme once:
|
|
236
298
|
|
|
237
|
-
```
|
|
238
|
-
|
|
239
|
-
:compress-images="true"
|
|
240
|
-
:compression-quality="0.8"
|
|
241
|
-
:max-width="1920"
|
|
242
|
-
:max-height="1080"
|
|
243
|
-
/>
|
|
299
|
+
```ts
|
|
300
|
+
import 'handy-uploader/style.css'
|
|
244
301
|
```
|
|
245
302
|
|
|
246
|
-
|
|
303
|
+
The easiest way to re-theme is with CSS variables, on the component or any parent:
|
|
247
304
|
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
'ja', // Japanese
|
|
258
|
-
'ko', // Korean
|
|
259
|
-
'ar' // Arabic (RTL)
|
|
260
|
-
]
|
|
305
|
+
```css
|
|
306
|
+
.hu-uploader {
|
|
307
|
+
--hu-primary: #7c3aed; /* links, focus, drop area */
|
|
308
|
+
--hu-button-bg: #7c3aed; /* Insert / Add buttons (or use btnColor) */
|
|
309
|
+
--hu-chip: #7c3aed; /* size chips */
|
|
310
|
+
--hu-radius: 16px; /* card corners */
|
|
311
|
+
--hu-media-height: 160px; /* preview height in the thumbnail view */
|
|
312
|
+
--hu-font: inherit;
|
|
313
|
+
}
|
|
261
314
|
```
|
|
262
315
|
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
- **Vue**: ^3.0.0
|
|
267
|
-
- **Vuetify**: ^3.0.0
|
|
268
|
-
|
|
269
|
-
### Browser Support
|
|
270
|
-
- Chrome 88+
|
|
271
|
-
- Firefox 85+
|
|
272
|
-
- Safari 14+
|
|
273
|
-
- Edge 88+
|
|
316
|
+
- Add the `hu-dark` class (on the component or a parent) for the dark preset.
|
|
317
|
+
- Built-in styles are single `hu-*` class selectors. They survive global resets such as Tailwind's preflight, and are easy to override with your own classes.
|
|
318
|
+
- Or skip `style.css` entirely and style the `hu-*` classes yourself.
|
|
274
319
|
|
|
275
|
-
|
|
276
|
-
- **Gzipped**: ~45KB
|
|
277
|
-
- **Minified**: ~120KB
|
|
320
|
+
The default theme uses `color-mix()` and `:has()` (Chrome/Edge 111+, Firefox 121+, Safari 16.4+). In older browsers it still works, with simpler focus and badge styling.
|
|
278
321
|
|
|
279
|
-
##
|
|
322
|
+
## 🧱 Building your own UI
|
|
280
323
|
|
|
281
|
-
|
|
324
|
+
Everything `HandyUploader` uses is exported:
|
|
282
325
|
|
|
283
|
-
|
|
326
|
+
- **`useUploader(filesRef, options)`:** the upload logic with no markup. It provides `add`, `stage` + `commit` (read files, let users edit them, then add), `remove`, `update`, `clear`, `errors` and `isProcessing`.
|
|
327
|
+
- **Components:** `HandyDropzone`, `HandyFileList`, `HandyDialog` and `HandyFileIcon`.
|
|
328
|
+
- **Framework-agnostic helpers:** `readFiles`, `prepareAttachments`, `compressDataUrl`, `generateVideoThumbnail`, `matchesAccept`, `formatBytes` and more. These have no Vue dependency.
|
|
284
329
|
|
|
285
|
-
```
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
}
|
|
296
|
-
}
|
|
330
|
+
```ts
|
|
331
|
+
import { ref } from 'vue'
|
|
332
|
+
import { useUploader, type DocumentAttachment } from 'handy-uploader'
|
|
333
|
+
|
|
334
|
+
const files = ref<DocumentAttachment[]>([])
|
|
335
|
+
const { add, remove, errors, isProcessing } = useUploader(files, {
|
|
336
|
+
maxFileSize: 5 * 1024 * 1024,
|
|
337
|
+
maxFileCount: 10,
|
|
338
|
+
accept: 'image/*',
|
|
339
|
+
imageCompressor: true
|
|
297
340
|
})
|
|
341
|
+
// <input type="file" multiple @change="add($event.target.files)">
|
|
298
342
|
```
|
|
299
343
|
|
|
300
|
-
|
|
344
|
+
## 🌍 Internationalization
|
|
301
345
|
|
|
302
|
-
|
|
303
|
-
<style scoped>
|
|
304
|
-
.handy-uploader {
|
|
305
|
-
--uploader-border-radius: 12px;
|
|
306
|
-
--uploader-primary-color: #1976D2;
|
|
307
|
-
--uploader-background: #f5f5f5;
|
|
308
|
-
}
|
|
309
|
-
</style>
|
|
310
|
-
```
|
|
346
|
+
Built-in languages: `en` (English), `fa` (Persian, RTL), `fr` (French), `ch` (Chinese), `ar` (Arabic, RTL).
|
|
311
347
|
|
|
312
|
-
|
|
348
|
+
To change texts or add a language, pass `customLang`. Start from the built-in strings:
|
|
313
349
|
|
|
314
|
-
|
|
350
|
+
```ts
|
|
351
|
+
import { languageData } from 'handy-uploader'
|
|
352
|
+
|
|
353
|
+
const customLang = {
|
|
354
|
+
...languageData,
|
|
355
|
+
de: { ...languageData.en, insertFile: 'Datei hinzufügen', add: 'Hinzufügen' /* … */ }
|
|
356
|
+
}
|
|
357
|
+
```
|
|
315
358
|
|
|
316
359
|
```vue
|
|
317
|
-
<
|
|
318
|
-
|
|
319
|
-
<h2>File Upload with Video Thumbnails</h2>
|
|
320
|
-
|
|
321
|
-
<ThumbnailUploader
|
|
322
|
-
:max-file-size="52428800"
|
|
323
|
-
:max-file-count="10"
|
|
324
|
-
:accepted-file-types="['image/*', 'video/*', 'application/pdf']"
|
|
325
|
-
:language="currentLanguage"
|
|
326
|
-
:theme="isDark ? 'dark' : 'light'"
|
|
327
|
-
:compress-images="true"
|
|
328
|
-
:compression-quality="0.8"
|
|
329
|
-
@files-selected="handleFilesSelected"
|
|
330
|
-
@file-removed="handleFileRemoved"
|
|
331
|
-
@error="handleError"
|
|
332
|
-
/>
|
|
333
|
-
|
|
334
|
-
<!-- Display selected files -->
|
|
335
|
-
<div v-if="selectedFiles.length" class="mt-4">
|
|
336
|
-
<h3>Selected Files:</h3>
|
|
337
|
-
<div v-for="file in selectedFiles" :key="file.id" class="file-item">
|
|
338
|
-
<img v-if="file.thumbnail" :src="file.thumbnail" alt="Thumbnail" width="100" />
|
|
339
|
-
<span>{{ file.name }} ({{ formatFileSize(file.size) }})</span>
|
|
340
|
-
</div>
|
|
341
|
-
</div>
|
|
342
|
-
</div>
|
|
343
|
-
</template>
|
|
360
|
+
<HandyUploader :custom-lang="customLang" lang="de" />
|
|
361
|
+
```
|
|
344
362
|
|
|
345
|
-
|
|
346
|
-
import { ref } from 'vue'
|
|
347
|
-
import { ThumbnailUploader, type FileData } from 'handy-uploader'
|
|
363
|
+
## 🛠️ Requirements
|
|
348
364
|
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
365
|
+
- **Vue** ^3.0.0: for `handy-uploader` and `handy-uploader/vuetify` (the Web Component includes its own)
|
|
366
|
+
- **Vuetify** ^3.0.0: optional, only for `handy-uploader/vuetify`
|
|
367
|
+
- Modern browsers (Chrome, Edge, Firefox, Safari). Video thumbnails need a browser that can play the video format.
|
|
352
368
|
|
|
353
|
-
|
|
354
|
-
selectedFiles.value = files
|
|
355
|
-
console.log('Files with thumbnails:', files)
|
|
356
|
-
}
|
|
369
|
+
Bundle size (minified, gzipped): `handy-uploader` about 10 KB JS + 3 KB CSS, plus about 6 KB of translations; `handy-uploader/vuetify` about 14 KB (Vue and Vuetify not included); `handy-uploader/element` about 55 KB, everything included.
|
|
357
370
|
|
|
358
|
-
|
|
359
|
-
console.log('File removed:', file.name)
|
|
360
|
-
}
|
|
371
|
+
## ⬆️ Upgrading from 2.x
|
|
361
372
|
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
373
|
+
- **Vuetify users:** change the import to `handy-uploader/vuetify`. Nothing else changes.
|
|
374
|
+
- **`maxFileSize` is now enforced in bytes**, as documented. 2.x compared it in kilobytes, so limits were about 1000× looser. If you tuned the value to the old behaviour, divide it by 1000.
|
|
375
|
+
- **`file.size` is always a number of bytes.** It used to be a string.
|
|
376
|
+
- **The package ships ES modules and CommonJS.** The UMD build was removed.
|
|
365
377
|
|
|
366
|
-
|
|
367
|
-
return bytes > 1024 * 1024
|
|
368
|
-
? `${(bytes / 1024 / 1024).toFixed(2)} MB`
|
|
369
|
-
: `${(bytes / 1024).toFixed(2)} KB`
|
|
370
|
-
}
|
|
371
|
-
</script>
|
|
372
|
-
```
|
|
378
|
+
See [CHANGELOG.md](CHANGELOG.md) for details.
|
|
373
379
|
|
|
374
380
|
## 🤝 Contributing
|
|
375
381
|
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
4.
|
|
382
|
-
5. Open a Pull Request
|
|
382
|
+
1. Fork the repository and create a branch.
|
|
383
|
+
2. `npm install`, then `npm run storybook` to work on the components.
|
|
384
|
+
3. Run `npm test`, `npm run type-check` and `npm run lint` before opening a pull request. The
|
|
385
|
+
browser tests (`npm run test:e2e`, Playwright: the Storybook stories and the apps in
|
|
386
|
+
`examples/`) need Chromium once: `npx playwright install chromium`.
|
|
387
|
+
4. Add a changeset (`npx changeset`) describing your change.
|
|
383
388
|
|
|
384
389
|
## 📄 License
|
|
385
390
|
|
|
386
|
-
|
|
391
|
+
MIT. See [LICENSE](LICENSE).
|
|
387
392
|
|
|
388
393
|
## 🔗 Links
|
|
389
394
|
|
|
390
|
-
- [GitHub
|
|
391
|
-
- [npm
|
|
392
|
-
- [
|
|
393
|
-
- [Issues](https://github.com/alijahanpak/
|
|
394
|
-
|
|
395
|
-
## 📊 Stats
|
|
395
|
+
- [GitHub repository](https://github.com/alijahanpak/handy-uploader)
|
|
396
|
+
- [npm package](https://www.npmjs.com/package/handy-uploader)
|
|
397
|
+
- [Live demo (Storybook)](https://alijahanpak.github.io/handy-uploader/)
|
|
398
|
+
- [Issues](https://github.com/alijahanpak/handy-uploader/issues)
|
|
396
399
|
|
|
397
400
|

|
|
398
401
|

|
|
399
|
-

|
|
400
|
-
|
|
401
|
-
---
|
|
402
|
-
|
|
403
|
-
**Made with ❤️ for the Vue.js community**
|