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
package/README.md CHANGED
@@ -3,38 +3,31 @@
3
3
  [![npm version](https://badge.fury.io/js/handy-uploader.svg)](https://badge.fury.io/js/handy-uploader)
4
4
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5
5
  [![Vue 3](https://img.shields.io/badge/Vue-3.x-4FC08D.svg)](https://vuejs.org/)
6
+ [![Web Component](https://img.shields.io/badge/Web_Component-React_·_Svelte_·_Angular_·_HTML-29abe2.svg)](#web-component-react-svelte-angular-plain-html)
6
7
  [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
7
8
 
8
- ## 🚀 [Live Demo](https://illustrious-griffin-257b43.netlify.app)
9
+ ## 🚀 [Live Demo](https://alijahanpak.github.io/handy-uploader/)
9
10
 
10
- A comprehensive Vue 3 file uploader component library with advanced features including **automatic video thumbnail generation**, multiple upload styles, and extensive file type support.
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
- ## ✨ Key Features
13
+ It comes in three flavours with **the same options**:
13
14
 
14
- ### 🎥 **Video Thumbnail Generation**
15
- - **Automatic thumbnail extraction** from video files using Canvas API
16
- - Support for **MP4, AVI, MOV, WMV, FLV, WebM** formats
17
- - Real-time thumbnail display with play button overlay
18
- - No external dependencies required
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
- ### 📁 **Comprehensive File Support**
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
- ### 🎨 **Multiple Upload Styles**
30
- - **ThumbnailUploader**: Grid-based layout with file previews
31
- - **TableUploader**: Table-based layout for detailed file information
32
- - **SimpleUploader**: Minimalist drag-and-drop interface
33
-
34
- ### 🌍 **Internationalization**
35
- - **8 languages**: English, Chinese, Spanish, French, German, Japanese, Korean, Arabic
36
- - RTL support for Arabic
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
- ```bash
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
- ### 1. Install Dependencies
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 { ThumbnailUploader } from 'handy-uploader'
81
- import type { FileData } from 'handy-uploader'
46
+ import { ref } from 'vue'
47
+ import { HandyUploader, type DocumentAttachment } from 'handy-uploader'
48
+ import 'handy-uploader/style.css'
82
49
 
83
- const handleFilesSelected = (files: FileData[]) => {
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
- ### 3. Setup Vuetify (Required)
68
+ ### With Vuetify
91
69
 
92
- ```typescript
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
- const vuetify = createVuetify()
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
- ## 📖 Component Usage
107
-
108
- ### ThumbnailUploader (Recommended)
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
- Perfect for media files with automatic video thumbnail generation:
87
+ const files = ref<DocumentAttachment[]>([])
88
+ </script>
111
89
 
112
- ```vue
113
90
  <template>
114
- <ThumbnailUploader
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
- <script setup>
127
- import { ThumbnailUploader } from 'handy-uploader'
97
+ ### Web Component (React, Svelte, Angular, plain HTML)
128
98
 
129
- const onFilesSelected = (files) => {
130
- // Video files will have thumbnails automatically generated
131
- files.forEach(file => {
132
- if (file.type === 'video') {
133
- console.log('Video thumbnail:', file.thumbnail) // Base64 thumbnail
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
- ### TableUploader
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
- Great for document management with detailed file information:
144
+ **Svelte 5**
143
145
 
144
- ```vue
145
- <template>
146
- <TableUploader
147
- :max-file-size="104857600"
148
- :max-file-count="20"
149
- :language="'en'"
150
- @files-selected="handleFiles"
151
- />
152
- </template>
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
- ### SimpleUploader
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
- Minimal drag-and-drop interface:
183
+ **Plain HTML** (no build step)
158
184
 
159
- ```vue
160
- <template>
161
- <SimpleUploader
162
- :max-file-size="5242880"
163
- :accepted-file-types="['image/*']"
164
- @files-selected="handleImages"
165
- />
166
- </template>
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
- ### Props
227
+ ### `HandyUploader` props
172
228
 
173
229
  | Prop | Type | Default | Description |
174
- |------|------|---------|-------------|
175
- | `maxFileSize` | `number` | `10485760` | Maximum file size in bytes (10MB) |
176
- | `maxFileCount` | `number` | `5` | Maximum number of files |
177
- | `acceptedFileTypes` | `string[]` | `['*']` | Accepted MIME types |
178
- | `language` | `string` | `'en'` | Language code |
179
- | `theme` | `string` | `'light'` | Theme variant |
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
- | `files-selected` | `FileData[]` | Emitted when files are selected |
186
- | `file-removed` | `FileData` | Emitted when a file is removed |
187
- | `error` | `Error` | Emitted on errors |
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
- ### FileData Interface
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
- ```typescript
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
- ### Video Thumbnail Generation
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
- The library automatically generates thumbnails for video files:
277
+ ### Data types
209
278
 
210
- ```javascript
211
- // Thumbnails are generated automatically
212
- const videoFile = {
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
- ```javascript
224
- // Automatic type detection
225
- const file = {
226
- name: 'document.pdf',
227
- type: 'document', // Auto-detected
228
- icon: 'mdi-file-pdf-box', // Auto-assigned
229
- color: 'red' // Auto-assigned
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
- ### Image Compression
295
+ ## 🎨 Styling (without Vuetify)
234
296
 
235
- Built-in image compression for large files:
297
+ Import the default theme once:
236
298
 
237
- ```vue
238
- <ThumbnailUploader
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
- ## 🌍 Internationalization
303
+ The easiest way to re-theme is with CSS variables, on the component or any parent:
247
304
 
248
- Supported languages:
249
-
250
- ```javascript
251
- const languages = [
252
- 'en', // English
253
- 'zh', // Chinese
254
- 'es', // Spanish
255
- 'fr', // French
256
- 'de', // German
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
- ## 🛠️ Technical Requirements
264
-
265
- ### Peer Dependencies
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
- ### Bundle Size
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
- ## 🎨 Customization
322
+ ## 🧱 Building your own UI
280
323
 
281
- ### Theming
324
+ Everything `HandyUploader` uses is exported:
282
325
 
283
- Works with Vuetify's theming system:
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
- ```javascript
286
- // vuetify.config.js
287
- export default createVuetify({
288
- theme: {
289
- themes: {
290
- light: {
291
- primary: '#1976D2',
292
- secondary: '#424242',
293
- // Custom theme colors
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
- ### Custom Styling
344
+ ## 🌍 Internationalization
301
345
 
302
- ```vue
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
- ## 📝 Examples
348
+ To change texts or add a language, pass `customLang`. Start from the built-in strings:
313
349
 
314
- ### Complete Example with All Features
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
- <template>
318
- <div class="uploader-container">
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
- <script setup lang="ts">
346
- import { ref } from 'vue'
347
- import { ThumbnailUploader, type FileData } from 'handy-uploader'
363
+ ## 🛠️ Requirements
348
364
 
349
- const selectedFiles = ref<FileData[]>([])
350
- const currentLanguage = ref('en')
351
- const isDark = ref(false)
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
- const handleFilesSelected = (files: FileData[]) => {
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
- const handleFileRemoved = (file: FileData) => {
359
- console.log('File removed:', file.name)
360
- }
371
+ ## ⬆️ Upgrading from 2.x
361
372
 
362
- const handleError = (error: Error) => {
363
- console.error('Upload error:', error)
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
- const formatFileSize = (bytes: number) => {
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
- We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
377
-
378
- 1. Fork the repository
379
- 2. Create your feature branch (`git checkout -b feature/amazing-feature`)
380
- 3. Commit your changes (`git commit -m 'Add amazing feature'`)
381
- 4. Push to the branch (`git push origin feature/amazing-feature`)
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
- This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
391
+ MIT. See [LICENSE](LICENSE).
387
392
 
388
393
  ## 🔗 Links
389
394
 
390
- - [GitHub Repository](https://github.com/alijahanpak/vue-file-uploader)
391
- - [npm Package](https://www.npmjs.com/package/handy-uploader)
392
- - [Documentation](https://github.com/alijahanpak/vue-file-uploader#readme)
393
- - [Issues](https://github.com/alijahanpak/vue-file-uploader/issues)
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
  ![npm downloads](https://img.shields.io/npm/dm/handy-uploader.svg)
398
401
  ![GitHub stars](https://img.shields.io/github/stars/alijahanpak/handy-uploader.svg)
399
- ![GitHub issues](https://img.shields.io/github/issues/alijahanpak/handy-uploader.svg)
400
-
401
- ---
402
-
403
- **Made with ❤️ for the Vue.js community**