handy-uploader 3.0.0 → 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 CHANGED
@@ -3,18 +3,20 @@
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 Vue 3 file uploader with **automatic video thumbnails**, **image compression**, three layouts (thumbnail, simple, table), per-file names, descriptions and tags, and translations for 5 languages.
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
- It comes in two flavours with **the same props and events**:
13
+ It comes in three flavours with **the same options**:
13
14
 
14
- | Import | Needs | Styling |
15
- | --- | --- | --- |
16
- | `handy-uploader` | Vue 3 only | Plain CSS, works with any CSS framework (Tailwind, Bootstrap, your own) |
17
- | `handy-uploader/vuetify` | Vue 3 + Vuetify 3 | Vuetify components |
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 |
18
20
 
19
21
  ## ✨ Features
20
22
 
@@ -33,7 +35,7 @@ It comes in two flavours with **the same props and events**:
33
35
  npm install handy-uploader
34
36
  ```
35
37
 
36
- For the Vuetify flavour, also install `vuetify@^3` (and `@mdi/font` for its icons).
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.
37
39
 
38
40
  ## 🚀 Quick Start
39
41
 
@@ -92,25 +94,133 @@ const files = ref<DocumentAttachment[]>([])
92
94
 
93
95
  Switching between the two is a one-line change, because the props are the same.
94
96
 
97
+ ### Web Component (React, Svelte, Angular, plain HTML)
98
+
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
+ )
123
+ }
124
+ ```
125
+
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
+ ```
143
+
144
+ **Svelte 5**
145
+
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>
157
+ ```
158
+
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
+ ```
182
+
183
+ **Plain HTML** (no build step)
184
+
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>
195
+ ```
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
+
95
201
  ## 🧭 Framework Support
96
202
 
97
- | Framework | Status |
203
+ | Framework | Use |
98
204
  | --- | --- |
99
205
  | **Vue 3** (any CSS) | ✅ `handy-uploader` |
100
206
  | **Vue 3 + Vuetify 3** | ✅ `handy-uploader/vuetify` |
101
- | **React, Svelte, Angular, plain HTML** | 🛠️ Planned as a Web Component (`<handy-uploader>`) in a 3.x release |
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` |
102
211
 
103
- The upload logic (reading files, validation, compression, video thumbnails) lives in a framework-free core that is already exported; see [Building your own UI](#-building-your-own-ui).
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).
104
213
 
105
214
  ## 📚 Documentation
106
215
 
107
- The [live demo](https://illustrious-griffin-257b43.netlify.app) is a Storybook with guides and an interactive example of every feature:
216
+ The [live demo](https://alijahanpak.github.io/handy-uploader/) is a Storybook with guides and an interactive example of every feature:
108
217
 
109
- - [Getting Started](https://illustrious-griffin-257b43.netlify.app/?path=/docs/guide-getting-started--docs)
110
- - [Feature Tour](https://illustrious-griffin-257b43.netlify.app/?path=/docs/guide-feature-tour--docs): every feature, with a link to try it
111
- - [Styling & Theming](https://illustrious-griffin-257b43.netlify.app/?path=/docs/guide-styling-theming--docs)
112
- - [Build Your Own UI](https://illustrious-griffin-257b43.netlify.app/?path=/docs/guide-build-your-own-ui--docs)
113
- - [Upgrading from 2.x](https://illustrious-griffin-257b43.netlify.app/?path=/docs/guide-upgrading-from-2-x--docs)
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
114
224
 
115
225
  ## ⚙️ API Reference
116
226
 
@@ -252,11 +362,11 @@ const customLang = {
252
362
 
253
363
  ## 🛠️ Requirements
254
364
 
255
- - **Vue** ^3.0.0
365
+ - **Vue** ^3.0.0: for `handy-uploader` and `handy-uploader/vuetify` (the Web Component includes its own)
256
366
  - **Vuetify** ^3.0.0: optional, only for `handy-uploader/vuetify`
257
367
  - Modern browsers (Chrome, Edge, Firefox, Safari). Video thumbnails need a browser that can play the video format.
258
368
 
259
- 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).
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.
260
370
 
261
371
  ## ⬆️ Upgrading from 2.x
262
372
 
@@ -271,7 +381,9 @@ See [CHANGELOG.md](CHANGELOG.md) for details.
271
381
 
272
382
  1. Fork the repository and create a branch.
273
383
  2. `npm install`, then `npm run storybook` to work on the components.
274
- 3. Run `npm test`, `npm run type-check` and `npm run lint` before opening a pull request.
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`.
275
387
  4. Add a changeset (`npx changeset`) describing your change.
276
388
 
277
389
  ## 📄 License
@@ -282,7 +394,7 @@ MIT. See [LICENSE](LICENSE).
282
394
 
283
395
  - [GitHub repository](https://github.com/alijahanpak/handy-uploader)
284
396
  - [npm package](https://www.npmjs.com/package/handy-uploader)
285
- - [Live demo (Storybook)](https://illustrious-griffin-257b43.netlify.app)
397
+ - [Live demo (Storybook)](https://alijahanpak.github.io/handy-uploader/)
286
398
  - [Issues](https://github.com/alijahanpak/handy-uploader/issues)
287
399
 
288
400
  ![npm downloads](https://img.shields.io/npm/dm/handy-uploader.svg)
@@ -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 {};