form-uploader 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.2.0
+
+- React (`form-uploader/react`) and Vue (`form-uploader/vue`) wrappers with submit/change events and reset/validate handles.
+- Layout config: half-width fields, titled groups, per-field help text.
+- `form-change` snapshots and opt-in `validateOnChange` with focus-safe live errors.
+- Single-file browser build (`dist/form-uploader.global.js`) for script-tag use.
+- Documented Angular and server-rendered (Django/Flask) patterns.
+
+## 0.1.0
+
+- Initial release: framework-agnostic core, `<form-uploader>` element, validation, multi-image upload, CSS-variable theming.

package/README.md

@@ -2,7 +2,7 @@
 
 One form for every site: contact fields plus multi-image upload. A framework-agnostic core plus a drop-in `<form-uploader>` custom element. Zero runtime dependencies, ESM only, TypeScript types included.
 
-- Drop-in element works in plain HTML, React, Vue, Svelte, anywhere.
+- Drop-in element works in plain HTML and anywhere, with React and Vue wrappers included.
 - Core module is DOM-free, so you can drive your own UI or run it in Node.
 - Validation, file limits, and `FormData` payload building included.
 - Themed with CSS variables, dark-mode aware, keyboard accessible.
@@ -65,35 +65,86 @@ el.reset();
 - `el.uploader` exposes the core instance below for direct control.
 - The `submit-label` attribute sets the button text (default `"Submit"`).
 
-## React
+## Frameworks
 
-Custom element props must be assigned, not passed as attributes. Use a ref:
+### React / Next.js
 
 ```jsx
-import { useEffect, useRef, useState } from "react";
-import "form-uploader/element";
-import { DEFAULT_FIELDS } from "form-uploader";
+import { FormUploader } from "form-uploader/react";
+
+<FormUploader
+  fields={fields}
+  files={{ maxFiles: 3 }}
+  submitLabel="Send"
+  onSubmit={async ({ formData }) => {
+    await fetch("/api/upload", { method: "POST", body: formData });
+  }}
+  onChange={({ values }) => console.log(values)}
+/>;
+```
+
+The wrapper is marked client-side, so Next.js App Router pages can import it directly, even from Server Components. `onChange` streams `{ values, files, errors, valid }` snapshots. A `ref` exposes `reset()`, `validate()`, `getValues()`, and `getFiles()`. Equal configs never wipe typed input, so inline props are safe. Requires `react >= 18`.
+
+### Vue
+
+```vue
+<script setup>
+import { FormUploader } from "form-uploader/vue";
+</script>
+
+<template>
+  <FormUploader :fields="fields" :files="{ maxFiles: 3 }" submit-label="Send" @submit="send" />
+</template>
+```
+
+Props are `fields`, `files`, `validateOnChange`, and `submitLabel`. Events are `submit` and `change`, carrying the same payloads as the element. `class`, `style`, and other attributes fall through to the element for placement. A template ref exposes `reset()`, `validate()`, `getValues()`, and `getFiles()`. Requires `vue ^3`.
+
+### Angular
+
+No wrapper needed: bind the element directly.
 
-export default function ContactForm() {
-  const formRef = useRef(null);
-  const [result, setResult] = useState(null);
-
-  useEffect(() => {
-    const el = formRef.current;
-    if (!el) return;
-    el.config = {
-      fields: [...DEFAULT_FIELDS, { name: "company", label: "Company" }],
-      files: { maxFiles: 3 },
-    };
-    el.onSubmit = async ({ values, files, formData }) => {
-      setResult({ values, files: files.map((file) => file.name) });
-    };
-  }, []);
-
-  return <form-uploader ref={formRef} submit-label="Send" />;
+```ts
+import "form-uploader/element";
+import { CUSTOM_ELEMENTS_SCHEMA, Component } from "@angular/core";
+import type { FormSubmitDetail, FormUploaderConfig } from "form-uploader";
+
+@Component({
+  selector: "app-contact",
+  standalone: true,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: `
+    <form-uploader
+      [config]="config"
+      submit-label="Send"
+      (form-submit)="onSubmit($event.detail)"
+    ></form-uploader>
+  `,
+})
+export class ContactComponent {
+  config: FormUploaderConfig = { files: { maxFiles: 3 } };
+
+  onSubmit(detail: FormSubmitDetail): void {
+    fetch("/api/upload", { method: "POST", body: detail.formData });
+  }
 }
 ```
 
+Import `form-uploader/element` once (for example in `main.ts`) to register the tag. `config` binds as a property and the events carry the same payloads as below. A `ViewChild` reference gives you `reset()` and the core `uploader` for anything else.
+
+### Server-rendered pages (Django, Flask, plain HTML)
+
+No build step. Pin a version and drop in a script tag:
+
+```html
+<script src="https://unpkg.com/form-uploader@0.2.0/dist/form-uploader.global.js"></script>
+<form-uploader submit-label="Send"></form-uploader>
+<script>
+  document.querySelector("form-uploader").onSubmit = async ({ formData }) => {
+    await fetch("/upload", { method: "POST", body: formData });
+  };
+</script>
+```
+
 ## Core (your own UI)
 
 ```js
@@ -136,6 +187,8 @@ Field options:
 - `required` (default `false`), `placeholder`
 - `minLength`, `maxLength`, counted in characters
 - `validate(value)` returning an error string or `null`
+- `width` (`full` default, `half` shares a row; stacks on narrow containers)
+- `help` (hint text under the input), `group` (name of a group below)
 
 File options:
 
@@ -145,10 +198,22 @@ File options:
 - `required` (default `false`)
 - Pass `files: false` to disable uploads entirely
 
+Top-level options:
+
+- `groups: [{ name, title, description }]` renders titled cards in order; fields without a group, or with an unknown one, render first
+- `validateOnChange` (default `false`): revalidate on every keystroke with live errors; focus is preserved
+
 Validation order per field is required, email format, length, then your `validate`, first failure wins. Email is checked only when non-empty. Phone has no format check since formats vary, so add `validate` or `minLength` if you need one.
 
 The payload is a `FormData` with one entry per field plus each file under `fieldName`, ready to `POST` to your backend.
 
+## Events
+
+Both events bubble and cross shadow DOM.
+
+- `form-submit`: a valid submit, detail `{ formData, values, files }`. Calling `preventDefault()` skips `onSubmit`.
+- `form-change`: every keystroke and file change, detail `{ values, files, errors, valid }`. `errors` and `valid` reflect the last validation run, so pair it with `validateOnChange: true` for live validity.
+
 ## Styling
 
 The element inherits your page font and adapts to light and dark mode automatically. Override any variable to theme it:
@@ -175,7 +240,7 @@ form-uploader {
 | `--fu-radius`          | `10px`                  | Inputs, dropzone, button      |
 | `--fu-radius-sm`       | `8px`                   | Preview cards                 |
 
-For deeper restyling, every part is exposed via `::part`: `form`, `field`, `label`, `input`, `error`, `dropzone`, `dropzone-title`, `dropzone-hint`, `file-input`, `previews`, `preview`, `remove`, `submit`.
+For deeper restyling, every part is exposed via `::part`: `form`, `field`, `label`, `input`, `help`, `error`, `group`, `group-title`, `group-description`, `dropzone`, `dropzone-title`, `dropzone-hint`, `file-input`, `previews`, `preview`, `remove`, `submit`.
 
 ```css
 form-uploader::part(submit) {

package/dist/core.d.ts

@@ -1,4 +1,5 @@
 export type FieldType = "text" | "email" | "tel" | "textarea";
+export type FieldWidth = "full" | "half";
 export interface FieldConfig {
     name: string;
     label?: string;
@@ -7,6 +8,9 @@ export interface FieldConfig {
     placeholder?: string;
     minLength?: number;
     maxLength?: number;
+    width?: FieldWidth;
+    help?: string;
+    group?: string;
     validate?: (value: string) => string | null;
 }
 export interface FileUploadConfig {
@@ -16,13 +20,21 @@ export interface FileUploadConfig {
     accept?: string;
     required?: boolean;
 }
+export interface FormGroup {
+    name: string;
+    title: string;
+    description?: string;
+}
 export interface FormUploaderConfig {
     fields?: FieldConfig[];
     files?: FileUploadConfig | false;
+    groups?: FormGroup[];
+    validateOnChange?: boolean;
 }
-export interface NormalizedField extends Omit<FieldConfig, "type" | "required"> {
+export interface NormalizedField extends Omit<FieldConfig, "type" | "required" | "width"> {
     type: FieldType;
     required: boolean;
+    width: FieldWidth;
 }
 export interface ResolvedFileUploadConfig {
     fieldName: string;
@@ -49,6 +61,12 @@ export interface FormSubmitDetail {
     values: Record<string, string>;
     files: File[];
 }
+export interface FormChangeDetail {
+    values: Record<string, string>;
+    files: File[];
+    errors: ValidationErrors;
+    valid: boolean;
+}
 export declare const DEFAULT_FIELDS: FieldConfig[];
 export declare const DEFAULT_FILE_CONFIG: ResolvedFileUploadConfig;
 export declare const FILES_ERROR_KEY = "files";

package/dist/core.js

@@ -21,6 +21,7 @@ export function createFormUploader(config = {}) {
         ...field,
         type: field.type ?? "text",
         required: field.required ?? false,
+        width: field.width ?? "full",
     }));
     const filesEnabled = config.files !== false;
     const fileConfig = {

package/dist/element.d.ts

@@ -1,6 +1,7 @@
 import { type FormSubmitDetail, type FormUploader, type FormUploaderConfig } from "./core.js";
 export declare const ELEMENT_NAME = "form-uploader";
 export declare const SUBMIT_EVENT = "form-submit";
+export declare const CHANGE_EVENT = "form-change";
 declare const BaseElement: typeof HTMLElement;
 export declare class FormUploaderElement extends BaseElement {
     private uploaderInstance;
@@ -17,7 +18,13 @@ export declare class FormUploaderElement extends BaseElement {
     attributeChangedCallback(): void;
     reset(): void;
     private get submitLabel();
+    private fieldHtml;
     private render;
+    private afterChange;
+    private emitChange;
+    private snapshotFocus;
+    private restoreFocus;
+    private focusFileInput;
     private handleSubmit;
     private syncPreviews;
     private revokePreviews;

package/dist/element.js

@@ -1,6 +1,7 @@
 import { FILES_ERROR_KEY, createFormUploader, } from "./core.js";
 export const ELEMENT_NAME = "form-uploader";
 export const SUBMIT_EVENT = "form-submit";
+export const CHANGE_EVENT = "form-change";
 const BaseElement = globalThis.HTMLElement ??
     class {
     };
@@ -19,7 +20,7 @@ function formatBytes(bytes) {
     return `${bytes} B`;
 }
 const STYLES = [
-    ":host { display: block; font: inherit; color-scheme: light dark; }",
+    ":host { display: block; font: inherit; color-scheme: light dark; container-type: inline-size; }",
     ":host {",
     "  --fu-accent: #2563eb;",
     "  --fu-accent-hover: #1d4ed8;",
@@ -45,8 +46,14 @@ const STYLES = [
     "    --fu-ring: rgb(96 165 250 / 0.35);",
     "  }",
     "}",
-    "form { display: grid; gap: 1rem; color: var(--fu-text); }",
-    ".field { min-width: 0; }",
+    "form { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; color: var(--fu-text); }",
+    ".field { min-width: 0; grid-column: span 2; }",
+    ".field.half { grid-column: span 1; }",
+    "@container (max-width: 28rem) { .field.half { grid-column: span 2; } }",
+    ".group { grid-column: span 2; display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; margin: 0; padding: 1rem; border: 1px solid var(--fu-border); border-radius: var(--fu-radius); background: var(--fu-surface); }",
+    ".group-title { grid-column: span 2; font-size: 0.875rem; font-weight: 600; }",
+    ".group-description { grid-column: span 2; font-size: 0.8125rem; color: var(--fu-muted); margin: 0; }",
+    ".help { font-size: 0.8125rem; color: var(--fu-muted); margin: 0.375rem 0 0; }",
     ".field > label:not(.dropzone) { display: grid; gap: 0.375rem; font-size: 0.875rem; font-weight: 500; }",
     "input, textarea { font: inherit; color: var(--fu-text); background: var(--fu-surface); border: 1px solid var(--fu-border); border-radius: var(--fu-radius); padding: 0.625rem 0.75rem; width: 100%; box-sizing: border-box; transition: border-color 0.15s ease, box-shadow 0.15s ease; }",
     "input::placeholder, textarea::placeholder { color: var(--fu-muted); opacity: 1; }",
@@ -120,6 +127,23 @@ export class FormUploaderElement extends BaseElement {
             return "Submit";
         return host.getAttribute("submit-label") || "Submit";
     }
+    fieldHtml(field, values, errors) {
+        const value = escapeHtml(values[field.name] ?? "");
+        const error = errors[field.name]
+            ? `<p class="error" part="error">${escapeHtml(errors[field.name])}</p>`
+            : "";
+        const label = escapeHtml(field.label || field.name);
+        const placeholder = field.placeholder ? ` placeholder="${escapeHtml(field.placeholder)}"` : "";
+        const required = field.required ? " required" : "";
+        const safeName = escapeHtml(field.name);
+        const invalid = errors[field.name] ? ` aria-invalid="true"` : "";
+        const width = field.width === "half" ? " half" : "";
+        const help = field.help ? `<p class="help" part="help">${escapeHtml(field.help)}</p>` : "";
+        const control = field.type === "textarea"
+            ? `<textarea part="input" data-field="${safeName}" rows="4"${placeholder}${required}${invalid}>${value}</textarea>`
+            : `<input part="input" data-field="${safeName}" type="${field.type}" value="${value}"${placeholder}${required}${invalid} />`;
+        return `<div class="field${width}" part="field"><label part="label"><span>${label}</span>${control}</label>${help}${error}</div>`;
+    }
     render() {
         const host = this;
         if (typeof host.attachShadow !== "function")
@@ -130,25 +154,30 @@ export class FormUploaderElement extends BaseElement {
         const errors = this.uploaderInstance.getErrors();
         const files = this.uploaderInstance.getFiles();
         const fileConfig = this.uploaderInstance.fileConfig;
-        const fieldsHtml = this.uploaderInstance.fields
-            .map((field) => {
-            const value = escapeHtml(values[field.name] ?? "");
-            const error = errors[field.name]
-                ? `<p class="error" part="error">${escapeHtml(errors[field.name])}</p>`
-                : "";
-            const label = escapeHtml(field.label || field.name);
-            const placeholder = field.placeholder
-                ? ` placeholder="${escapeHtml(field.placeholder)}"`
+        const groups = this.elementConfig.groups ?? [];
+        const knownGroups = new Set(groups.map((group) => group.name));
+        const renderField = (field) => this.fieldHtml(field, values, errors);
+        const ungroupedHtml = this.uploaderInstance.fields
+            .filter((field) => !field.group || !knownGroups.has(field.group))
+            .map(renderField)
+            .join("");
+        const groupsHtml = groups
+            .map((group) => {
+            const members = this.uploaderInstance.fields.filter((field) => field.group === group.name);
+            if (members.length === 0)
+                return "";
+            const title = escapeHtml(group.title);
+            const description = group.description
+                ? `<p class="group-description" part="group-description">${escapeHtml(group.description)}</p>`
                 : "";
-            const required = field.required ? " required" : "";
-            const safeName = escapeHtml(field.name);
-            const invalid = errors[field.name] ? ` aria-invalid="true"` : "";
-            const control = field.type === "textarea"
-                ? `<textarea part="input" data-field="${safeName}" rows="4"${placeholder}${required}${invalid}>${value}</textarea>`
-                : `<input part="input" data-field="${safeName}" type="${field.type}" value="${value}"${placeholder}${required}${invalid} />`;
-            return `<div class="field" part="field"><label part="label"><span>${label}</span>${control}</label>${error}</div>`;
+            return (`<div class="group" part="group" role="group" aria-label="${title}">` +
+                `<span class="group-title" part="group-title">${title}</span>` +
+                description +
+                members.map(renderField).join("") +
+                `</div>`);
         })
             .join("");
+        const fieldsHtml = ungroupedHtml + groupsHtml;
         const fileError = errors[FILES_ERROR_KEY] ?? this.fileNotice;
         const dropzoneTitle = fileConfig.accept === "image/*" ? "Choose images" : "Choose files";
         const acceptLabel = fileConfig.accept === "image/*" ? "Images" : fileConfig.accept || "Files";
@@ -181,8 +210,10 @@ export class FormUploaderElement extends BaseElement {
         shadow.querySelectorAll("[data-field]").forEach((el) => {
             el.addEventListener("input", () => {
                 const name = el.dataset.field;
-                if (name)
-                    this.uploaderInstance.setValue(name, el.value);
+                if (!name)
+                    return;
+                this.uploaderInstance.setValue(name, el.value);
+                this.afterChange();
             });
         });
         const fileInput = shadow.querySelector("[data-files]");
@@ -195,22 +226,101 @@ export class FormUploaderElement extends BaseElement {
                         : null;
             }
             fileInput.value = "";
+            if (this.elementConfig.validateOnChange)
+                this.uploaderInstance.validate();
             this.render();
+            this.focusFileInput();
+            this.emitChange();
         });
         shadow.querySelectorAll("[data-remove]").forEach((button) => {
             button.addEventListener("click", () => {
                 this.uploaderInstance.removeFile(Number(button.dataset.remove));
                 this.fileNotice = null;
+                if (this.elementConfig.validateOnChange)
+                    this.uploaderInstance.validate();
                 this.render();
+                this.focusFileInput();
+                this.emitChange();
             });
         });
     }
+    afterChange() {
+        if (this.elementConfig.validateOnChange) {
+            const focus = this.snapshotFocus();
+            this.uploaderInstance.validate();
+            this.render();
+            this.restoreFocus(focus);
+        }
+        this.emitChange();
+    }
+    emitChange() {
+        const errors = this.uploaderInstance.getErrors();
+        const detail = {
+            values: this.uploaderInstance.getValues(),
+            files: this.uploaderInstance.getFiles(),
+            errors,
+            valid: Object.keys(errors).length === 0,
+        };
+        const host = this;
+        host.dispatchEvent(new CustomEvent(CHANGE_EVENT, { detail, bubbles: true, composed: true }));
+    }
+    snapshotFocus() {
+        const host = this;
+        const active = host.shadowRoot?.activeElement;
+        const name = active?.dataset?.field ?? null;
+        let start = -1;
+        let end = -1;
+        if (name && active && (active.tagName === "INPUT" || active.tagName === "TEXTAREA")) {
+            try {
+                const control = active;
+                start = control.selectionStart ?? -1;
+                end = control.selectionEnd ?? -1;
+            }
+            catch {
+                start = -1;
+                end = -1;
+            }
+        }
+        return { name, start, end };
+    }
+    restoreFocus(focus) {
+        if (!focus.name)
+            return;
+        const host = this;
+        const controls = host.shadowRoot?.querySelectorAll("[data-field]");
+        let next = null;
+        if (controls) {
+            for (const el of controls) {
+                if (el.dataset.field === focus.name)
+                    next = el;
+            }
+        }
+        if (next)
+            next.focus({ preventScroll: true });
+        if (focus.start >= 0 && next && (next.tagName === "INPUT" || next.tagName === "TEXTAREA")) {
+            try {
+                next.setSelectionRange(focus.start, focus.end);
+            }
+            catch {
+                return;
+            }
+        }
+    }
+    focusFileInput() {
+        const host = this;
+        const fileInput = host.shadowRoot?.querySelector("[data-files]");
+        fileInput?.focus({ preventScroll: true });
+    }
     async handleSubmit() {
         this.fileNotice = null;
         const { valid } = this.uploaderInstance.validate();
         this.render();
-        if (!valid)
+        if (!valid) {
+            const host = this;
+            const firstInvalid = host.shadowRoot?.querySelector("[aria-invalid='true']");
+            firstInvalid?.focus();
             return;
+        }
         const detail = {
             formData: this.uploaderInstance.buildPayload(),
             values: this.uploaderInstance.getValues(),

package/dist/form-uploader.global.js

@@ -0,0 +1,2 @@
+"use strict";(()=>{var E=[{name:"name",label:"Name",type:"text",required:!0},{name:"email",label:"Email",type:"email",required:!0},{name:"phone",label:"Phone",type:"tel",required:!0},{name:"description",label:"Description",type:"textarea",required:!1}];for(let d of E)Object.freeze(d);Object.freeze(E);var U={fieldName:"images",maxFiles:5,maxSize:5*1024*1024,accept:"image/*",required:!1},y="files",k=/^[^\s@]+@[^\s@]+\.[^\s@]+$/;function L(d={}){let h=(d.fields??E).map(t=>({...t,type:t.type??"text",required:t.required??!1,width:t.width??"full"})),e=d.files!==!1,i={...U,...d.files===!1||d.files===void 0?{}:d.files},s={},n=[],c={},u=()=>{s={};for(let t of h)s[t.name]=""};u();let f=t=>h.find(o=>o.name===t);function g(t){let o=i.accept.trim();if(o==="")return!0;let l=t.type.toLowerCase(),r=t.name.toLowerCase();return o.split(",").map(a=>a.trim().toLowerCase()).filter(Boolean).some(a=>a.endsWith("/*")?l.startsWith(a.slice(0,-1)):a.startsWith(".")?r.endsWith(a):l===a)}function m(t,o){return f(t)?(s[t]=o,!0):!1}function v(t){let o=Array.from(t),l=[],r=[];if(!e){for(let a of o)r.push({file:a,reason:"File uploads are disabled."});return{added:l,rejected:r}}for(let a of o){if(n.length+l.length>=i.maxFiles){r.push({file:a,reason:`Only ${i.maxFiles} file(s) allowed.`});continue}if(a.size>i.maxSize){r.push({file:a,reason:`"${a.name}" exceeds the size limit.`});continue}if(!g(a)){r.push({file:a,reason:`"${a.name}" is not an accepted file type.`});continue}l.push(a)}return n=n.concat(l),{added:l,rejected:r}}function F(t){return t<0||t>=n.length?!1:(n=n.slice(0,t).concat(n.slice(t+1)),!0)}function x(t,o){let l=t.label||t.name;return t.required&&o.trim()===""?`${l} is required.`:t.type==="email"&&o.trim()!==""&&!k.test(o.trim())?"Enter a valid email address.":t.minLength!==void 0&&o.length<t.minLength?`${l} must be at least ${t.minLength} characters.`:t.maxLength!==void 0&&o.length>t.maxLength?`${l} must be at most ${t.maxLength} characters.`:t.validate?t.validate(o):null}function b(){let t={};for(let o of h){let l=x(o,s[o.name]??"");l&&(t[o.name]=l)}return e&&i.required&&n.length===0&&(t[y]="At least one file is required."),c=t,{valid:Object.keys(t).length===0,errors:{...t}}}function w(){let t=new FormData;for(let o of h)t.append(o.name,s[o.name]??"");if(e)for(let o of n)t.append(i.fieldName,o);return t}function $(){u(),n=[],c={}}return{fields:h,filesEnabled:e,fileConfig:i,setValue:m,getValues:()=>({...s}),getFiles:()=>[...n],addFiles:v,removeFile:F,clearFiles:()=>{n=[]},validate:b,getErrors:()=>({...c}),buildPayload:w,reset:$}}var z="form-uploader",H="form-submit",M="form-change",N=globalThis.HTMLElement??class{};function p(d){return d.replace(/&/g,"&amp;").replace(/</g,"&lt;").replace(/>/g,"&gt;").replace(/"/g,"&quot;")}function S(d){return d>=1024*1024?`${Math.round(d/(1024*1024))} MB`:d>=1024?`${Math.round(d/1024)} KB`:`${d} B`}var q=[":host { display: block; font: inherit; color-scheme: light dark; container-type: inline-size; }",":host {","  --fu-accent: #2563eb;","  --fu-accent-hover: #1d4ed8;","  --fu-accent-contrast: #ffffff;","  --fu-text: #1c1917;","  --fu-muted: #57534e;","  --fu-border: #d6d3d1;","  --fu-surface: #ffffff;","  --fu-surface-soft: #f5f5f4;","  --fu-error: #b91c1c;","  --fu-ring: rgb(37 99 235 / 0.25);","  --fu-radius: 10px;","  --fu-radius-sm: 8px;","}","@media (prefers-color-scheme: dark) {","  :host {","    --fu-text: #e7e5e4;","    --fu-muted: #a8a29e;","    --fu-border: #44403c;","    --fu-surface: #1c1917;","    --fu-surface-soft: #292524;","    --fu-error: #f87171;","    --fu-ring: rgb(96 165 250 / 0.35);","  }","}","form { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; color: var(--fu-text); }",".field { min-width: 0; grid-column: span 2; }",".field.half { grid-column: span 1; }","@container (max-width: 28rem) { .field.half { grid-column: span 2; } }",".group { grid-column: span 2; display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; margin: 0; padding: 1rem; border: 1px solid var(--fu-border); border-radius: var(--fu-radius); background: var(--fu-surface); }",".group-title { grid-column: span 2; font-size: 0.875rem; font-weight: 600; }",".group-description { grid-column: span 2; font-size: 0.8125rem; color: var(--fu-muted); margin: 0; }",".help { font-size: 0.8125rem; color: var(--fu-muted); margin: 0.375rem 0 0; }",".field > label:not(.dropzone) { display: grid; gap: 0.375rem; font-size: 0.875rem; font-weight: 500; }","input, textarea { font: inherit; color: var(--fu-text); background: var(--fu-surface); border: 1px solid var(--fu-border); border-radius: var(--fu-radius); padding: 0.625rem 0.75rem; width: 100%; box-sizing: border-box; transition: border-color 0.15s ease, box-shadow 0.15s ease; }","input::placeholder, textarea::placeholder { color: var(--fu-muted); opacity: 1; }","input:focus-visible, textarea:focus-visible { outline: none; border-color: var(--fu-accent); box-shadow: 0 0 0 3px var(--fu-ring); }","input[aria-invalid='true'], textarea[aria-invalid='true'] { border-color: var(--fu-error); }","input[aria-invalid='true']:focus-visible, textarea[aria-invalid='true']:focus-visible { box-shadow: 0 0 0 3px color-mix(in srgb, var(--fu-error) 25%, transparent); }","textarea { min-height: 6rem; resize: vertical; }",".error { color: var(--fu-error); font-size: 0.8125rem; margin: 0.375rem 0 0; }",".dropzone { position: relative; display: grid; justify-items: center; gap: 0.375rem; padding: 1.5rem 1rem; border: 1.5px dashed var(--fu-border); border-radius: var(--fu-radius); background: var(--fu-surface-soft); cursor: pointer; text-align: center; transition: border-color 0.15s ease, box-shadow 0.15s ease; }",".dropzone:hover { border-color: var(--fu-accent); }",".dropzone:focus-within { outline: none; border-color: var(--fu-accent); box-shadow: 0 0 0 3px var(--fu-ring); }",".dropzone input { position: absolute; width: 1px; height: 1px; opacity: 0; overflow: hidden; }",".dropzone-mark { display: grid; place-items: center; width: 2.5rem; height: 2.5rem; border-radius: 999px; background: var(--fu-accent); color: var(--fu-accent-contrast); font-size: 1.5rem; font-weight: 300; line-height: 1; }",".dropzone-title { font-size: 0.875rem; font-weight: 600; }",".dropzone-hint { font-size: 0.8125rem; font-weight: 400; color: var(--fu-muted); }",".previews { display: grid; grid-template-columns: repeat(auto-fill, minmax(6rem, 1fr)); gap: 0.625rem; margin-top: 0.625rem; }",".preview { margin: 0; position: relative; border: 1px solid var(--fu-border); border-radius: var(--fu-radius-sm); overflow: hidden; background: var(--fu-surface); }",".preview img { width: 100%; height: 5.25rem; object-fit: cover; display: block; background: var(--fu-surface-soft); }",".preview figcaption { font-size: 0.7rem; padding: 0.25rem 0.375rem; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; color: var(--fu-muted); }",".preview button { position: absolute; top: 0.25rem; right: 0.25rem; width: 1.5rem; height: 1.5rem; display: grid; place-items: center; padding: 0; border: none; border-radius: 999px; background: rgb(0 0 0 / 0.6); color: #ffffff; font-size: 1rem; line-height: 1; cursor: pointer; }",".preview button:hover { background: rgb(0 0 0 / 0.8); }","button[type='submit'] { justify-self: start; font: inherit; font-weight: 600; color: var(--fu-accent-contrast); background: var(--fu-accent); border: 1px solid transparent; border-radius: var(--fu-radius); padding: 0.625rem 1.25rem; cursor: pointer; transition: background-color 0.15s ease, transform 0.1s ease, box-shadow 0.15s ease; }","button[type='submit']:hover { background: var(--fu-accent-hover); }","button[type='submit']:active { transform: scale(0.98); }","button[type='submit']:focus-visible { outline: none; box-shadow: 0 0 0 3px var(--fu-ring); }","@media (prefers-reduced-motion: reduce) {","  *, *::before, *::after { transition: none; }","}"].join(`
+`),C=class extends N{constructor(){super(...arguments);this.uploaderInstance=L({});this.elementConfig={};this.previewUrls=new Map;this.fileNotice=null}static get observedAttributes(){return["submit-label"]}get config(){return this.elementConfig}set config(e){this.elementConfig=e??{},this.uploaderInstance=L(this.elementConfig),this.fileNotice=null,this.revokePreviews(),this.render()}get uploader(){return this.uploaderInstance}connectedCallback(){this.render()}disconnectedCallback(){this.revokePreviews()}attributeChangedCallback(){this.render()}reset(){this.uploaderInstance.reset(),this.fileNotice=null,this.render()}get submitLabel(){let e=this;return typeof e.getAttribute!="function"?"Submit":e.getAttribute("submit-label")||"Submit"}fieldHtml(e,i,s){let n=p(i[e.name]??""),c=s[e.name]?`<p class="error" part="error">${p(s[e.name])}</p>`:"",u=p(e.label||e.name),f=e.placeholder?` placeholder="${p(e.placeholder)}"`:"",g=e.required?" required":"",m=p(e.name),v=s[e.name]?' aria-invalid="true"':"",F=e.width==="half"?" half":"",x=e.help?`<p class="help" part="help">${p(e.help)}</p>`:"",b=e.type==="textarea"?`<textarea part="input" data-field="${m}" rows="4"${f}${g}${v}>${n}</textarea>`:`<input part="input" data-field="${m}" type="${e.type}" value="${n}"${f}${g}${v} />`;return`<div class="field${F}" part="field"><label part="label"><span>${u}</span>${b}</label>${x}${c}</div>`}render(){let e=this;if(typeof e.attachShadow!="function")return;let i=e.shadowRoot??e.attachShadow({mode:"open"});this.syncPreviews();let s=this.uploaderInstance.getValues(),n=this.uploaderInstance.getErrors(),c=this.uploaderInstance.getFiles(),u=this.uploaderInstance.fileConfig,f=this.elementConfig.groups??[],g=new Set(f.map(r=>r.name)),m=r=>this.fieldHtml(r,s,n),v=this.uploaderInstance.fields.filter(r=>!r.group||!g.has(r.group)).map(m).join(""),F=f.map(r=>{let a=this.uploaderInstance.fields.filter(R=>R.group===r.name);if(a.length===0)return"";let T=p(r.title),I=r.description?`<p class="group-description" part="group-description">${p(r.description)}</p>`:"";return`<div class="group" part="group" role="group" aria-label="${T}"><span class="group-title" part="group-title">${T}</span>`+I+a.map(m).join("")+"</div>"}).join(""),x=v+F,b=n[y]??this.fileNotice,w=u.accept==="image/*"?"Choose images":"Choose files",t=`${u.accept==="image/*"?"Images":u.accept||"Files"} up to ${S(u.maxSize)} each, max ${u.maxFiles} ${u.maxFiles===1?"file":"files"}`,o=this.uploaderInstance.filesEnabled?`<div class="field" part="field"><label class="dropzone" part="label dropzone"><span class="dropzone-mark" aria-hidden="true">+</span><span class="dropzone-title" part="dropzone-title">${w}</span><span class="dropzone-hint" part="dropzone-hint">${p(t)}</span><input part="file-input" data-files type="file" multiple accept="${p(u.accept)}" /></label>`+(b?`<p class="error" part="error">${p(b)}</p>`:"")+`<div class="previews" part="previews">${c.map((r,a)=>`<figure class="preview" part="preview"><img src="${this.previewUrls.get(r)??""}" alt="${p(r.name)}" /><figcaption>${p(r.name)}</figcaption><button type="button" part="remove" data-remove="${a}" aria-label="Remove ${p(r.name)}">\xD7</button></figure>`).join("")}</div></div>`:"";i.innerHTML=`<style>${q}</style><form part="form" novalidate>${x}${o}<button type="submit" part="submit">${p(this.submitLabel)}</button></form>`,i.querySelector("form")?.addEventListener("submit",r=>{r.preventDefault(),this.handleSubmit()}),i.querySelectorAll("[data-field]").forEach(r=>{r.addEventListener("input",()=>{let a=r.dataset.field;a&&(this.uploaderInstance.setValue(a,r.value),this.afterChange())})});let l=i.querySelector("[data-files]");l?.addEventListener("change",()=>{if(l.files){let r=this.uploaderInstance.addFiles(l.files);this.fileNotice=r.rejected.length>0?r.rejected.map(a=>a.reason).join(" "):null}l.value="",this.elementConfig.validateOnChange&&this.uploaderInstance.validate(),this.render(),this.focusFileInput(),this.emitChange()}),i.querySelectorAll("[data-remove]").forEach(r=>{r.addEventListener("click",()=>{this.uploaderInstance.removeFile(Number(r.dataset.remove)),this.fileNotice=null,this.elementConfig.validateOnChange&&this.uploaderInstance.validate(),this.render(),this.focusFileInput(),this.emitChange()})})}afterChange(){if(this.elementConfig.validateOnChange){let e=this.snapshotFocus();this.uploaderInstance.validate(),this.render(),this.restoreFocus(e)}this.emitChange()}emitChange(){let e=this.uploaderInstance.getErrors(),i={values:this.uploaderInstance.getValues(),files:this.uploaderInstance.getFiles(),errors:e,valid:Object.keys(e).length===0};this.dispatchEvent(new CustomEvent(M,{detail:i,bubbles:!0,composed:!0}))}snapshotFocus(){let i=this.shadowRoot?.activeElement,s=i?.dataset?.field??null,n=-1,c=-1;if(s&&i&&(i.tagName==="INPUT"||i.tagName==="TEXTAREA"))try{let u=i;n=u.selectionStart??-1,c=u.selectionEnd??-1}catch{n=-1,c=-1}return{name:s,start:n,end:c}}restoreFocus(e){if(!e.name)return;let s=this.shadowRoot?.querySelectorAll("[data-field]"),n=null;if(s)for(let c of s)c.dataset.field===e.name&&(n=c);if(n&&n.focus({preventScroll:!0}),e.start>=0&&n&&(n.tagName==="INPUT"||n.tagName==="TEXTAREA"))try{n.setSelectionRange(e.start,e.end)}catch{return}}focusFileInput(){this.shadowRoot?.querySelector("[data-files]")?.focus({preventScroll:!0})}async handleSubmit(){this.fileNotice=null;let{valid:e}=this.uploaderInstance.validate();if(this.render(),!e){this.shadowRoot?.querySelector("[aria-invalid='true']")?.focus();return}let i={formData:this.uploaderInstance.buildPayload(),values:this.uploaderInstance.getValues(),files:this.uploaderInstance.getFiles()};!this.dispatchEvent(new CustomEvent(H,{detail:i,bubbles:!0,composed:!0}))||await this.onSubmit?.(i)}syncPreviews(){let e=this.uploaderInstance.getFiles();for(let[i,s]of this.previewUrls)e.includes(i)||(URL.revokeObjectURL(s),this.previewUrls.delete(i));if(!(typeof URL>"u"||typeof URL.createObjectURL!="function"))for(let i of e)this.previewUrls.has(i)||this.previewUrls.set(i,URL.createObjectURL(i))}revokePreviews(){for(let e of this.previewUrls.values())typeof URL<"u"&&typeof URL.revokeObjectURL=="function"&&URL.revokeObjectURL(e);this.previewUrls.clear()}};typeof customElements<"u"&&!customElements.get(z)&&customElements.define(z,C);})();

package/dist/react.d.ts

@@ -0,0 +1,20 @@
+import type { CSSProperties } from "react";
+import "./element.js";
+import type { FieldConfig, FileUploadConfig, FormChangeDetail, FormSubmitDetail, ValidationResult } from "./core.js";
+export interface ReactFormUploaderProps {
+    fields?: FieldConfig[];
+    files?: FileUploadConfig | false;
+    validateOnChange?: boolean;
+    submitLabel?: string;
+    className?: string;
+    style?: CSSProperties;
+    onSubmit?: (detail: FormSubmitDetail) => void | Promise<void>;
+    onChange?: (detail: FormChangeDetail) => void;
+}
+export interface ReactFormUploaderHandle {
+    reset(): void;
+    validate(): ValidationResult;
+    getValues(): Record<string, string>;
+    getFiles(): File[];
+}
+export declare const FormUploader: import("react").ForwardRefExoticComponent<ReactFormUploaderProps & import("react").RefAttributes<ReactFormUploaderHandle>>;

package/dist/react.js

@@ -0,0 +1,81 @@
+"use client";
+import { createElement, forwardRef, useEffect, useImperativeHandle, useRef } from "react";
+import "./element.js";
+function isSameValue(left, right) {
+    if (Object.is(left, right))
+        return true;
+    if (typeof left !== "object" || typeof right !== "object" || left === null || right === null) {
+        return false;
+    }
+    if (Array.isArray(left) !== Array.isArray(right))
+        return false;
+    const leftRecord = left;
+    const rightRecord = right;
+    const leftKeys = Object.keys(leftRecord);
+    if (leftKeys.length !== Object.keys(rightRecord).length)
+        return false;
+    return leftKeys.every((key) => isSameValue(leftRecord[key], rightRecord[key]));
+}
+export const FormUploader = forwardRef(function FormUploader(props, ref) {
+    const hostRef = useRef(null);
+    const elRef = useRef(null);
+    const appliedRef = useRef(null);
+    const submitRef = useRef(props.onSubmit);
+    submitRef.current = props.onSubmit;
+    const changeRef = useRef(props.onChange);
+    changeRef.current = props.onChange;
+    useEffect(() => {
+        const host = hostRef.current;
+        if (!host)
+            return;
+        const el = document.createElement("form-uploader");
+        host.appendChild(el);
+        elRef.current = el;
+        el.onSubmit = (detail) => {
+            void submitRef.current?.(detail);
+        };
+        const handleChange = (event) => {
+            changeRef.current?.(event.detail);
+        };
+        el.addEventListener("form-change", handleChange);
+        return () => {
+            el.removeEventListener("form-change", handleChange);
+            el.onSubmit = undefined;
+            host.removeChild(el);
+            if (elRef.current === el)
+                elRef.current = null;
+            appliedRef.current = null;
+        };
+    }, []);
+    useEffect(() => {
+        const el = elRef.current;
+        if (!el)
+            return;
+        const next = {
+            fields: props.fields,
+            files: props.files,
+            validateOnChange: props.validateOnChange,
+        };
+        if (appliedRef.current && isSameValue(appliedRef.current, next))
+            return;
+        appliedRef.current = next;
+        el.config = next;
+        if (props.submitLabel === undefined)
+            el.removeAttribute("submit-label");
+        else
+            el.setAttribute("submit-label", props.submitLabel);
+    });
+    useImperativeHandle(ref, () => ({
+        reset: () => {
+            elRef.current?.reset();
+        },
+        validate: () => elRef.current?.uploader.validate() ?? { valid: false, errors: {} },
+        getValues: () => elRef.current?.uploader.getValues() ?? {},
+        getFiles: () => elRef.current?.uploader.getFiles() ?? [],
+    }), []);
+    return createElement("div", {
+        ref: hostRef,
+        className: props.className,
+        style: props.style,
+    });
+});

package/dist/vue.d.ts

@@ -0,0 +1,51 @@
+import type { PropType } from "vue";
+import "./element.js";
+import type { FieldConfig, FileUploadConfig, FormChangeDetail, FormSubmitDetail } from "./core.js";
+export declare const FormUploader: import("vue").DefineComponent<import("vue").ExtractPropTypes<{
+    fields: {
+        type: PropType<FieldConfig[]>;
+        default: undefined;
+    };
+    files: {
+        type: PropType<FileUploadConfig | false>;
+        default: undefined;
+    };
+    validateOnChange: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    submitLabel: {
+        type: StringConstructor;
+        default: undefined;
+    };
+}>, () => import("vue").VNode<import("vue").RendererNode, import("vue").RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, import("vue").ComponentOptionsMixin, import("vue").ComponentOptionsMixin, {
+    submit: (_detail: FormSubmitDetail) => true;
+    change: (_detail: FormChangeDetail) => true;
+}, string, import("vue").PublicProps, Readonly<import("vue").ExtractPropTypes<{
+    fields: {
+        type: PropType<FieldConfig[]>;
+        default: undefined;
+    };
+    files: {
+        type: PropType<FileUploadConfig | false>;
+        default: undefined;
+    };
+    validateOnChange: {
+        type: BooleanConstructor;
+        default: undefined;
+    };
+    submitLabel: {
+        type: StringConstructor;
+        default: undefined;
+    };
+}>> & Readonly<{
+    onChange?: ((_detail: FormChangeDetail) => any) | undefined;
+    onSubmit?: ((_detail: FormSubmitDetail) => any) | undefined;
+}>, {
+    fields: FieldConfig[];
+    files: false | FileUploadConfig;
+    validateOnChange: boolean;
+    submitLabel: string;
+}, {}, {}, {}, string, import("vue").ComponentProvideOptions, true, {}, any>;

package/dist/vue.js

@@ -0,0 +1,82 @@
+import { defineComponent, h, onBeforeUnmount, onMounted, ref, watch } from "vue";
+import "./element.js";
+function isSameValue(left, right) {
+    if (Object.is(left, right))
+        return true;
+    if (typeof left !== "object" || typeof right !== "object" || left === null || right === null) {
+        return false;
+    }
+    if (Array.isArray(left) !== Array.isArray(right))
+        return false;
+    const leftRecord = left;
+    const rightRecord = right;
+    const leftKeys = Object.keys(leftRecord);
+    if (leftKeys.length !== Object.keys(rightRecord).length)
+        return false;
+    return leftKeys.every((key) => isSameValue(leftRecord[key], rightRecord[key]));
+}
+export const FormUploader = defineComponent({
+    name: "FormUploader",
+    props: {
+        fields: { type: Array, default: undefined },
+        files: { type: [Object, Boolean], default: undefined },
+        validateOnChange: { type: Boolean, default: undefined },
+        submitLabel: { type: String, default: undefined },
+    },
+    emits: {
+        submit: (_detail) => true,
+        change: (_detail) => true,
+    },
+    setup(props, { emit, expose }) {
+        const elRef = ref(null);
+        let applied = null;
+        const applyConfig = (force = false) => {
+            const el = elRef.value;
+            if (!el)
+                return;
+            const next = {
+                fields: props.fields,
+                files: props.files,
+                validateOnChange: props.validateOnChange,
+            };
+            if (!force && applied && isSameValue(applied, next))
+                return;
+            applied = next;
+            el.config = next;
+            if (props.submitLabel === undefined)
+                el.removeAttribute("submit-label");
+            else
+                el.setAttribute("submit-label", props.submitLabel);
+        };
+        const handleChange = (event) => {
+            emit("change", event.detail);
+        };
+        onMounted(() => {
+            const el = elRef.value;
+            if (!el)
+                return;
+            applyConfig(true);
+            el.onSubmit = (detail) => {
+                emit("submit", detail);
+            };
+            el.addEventListener("form-change", handleChange);
+        });
+        onBeforeUnmount(() => {
+            const el = elRef.value;
+            if (!el)
+                return;
+            el.removeEventListener("form-change", handleChange);
+            el.onSubmit = undefined;
+        });
+        watch(() => [props.fields, props.files, props.validateOnChange, props.submitLabel], () => {
+            applyConfig();
+        });
+        expose({
+            reset: () => elRef.value?.reset(),
+            validate: () => elRef.value?.uploader.validate() ?? { valid: false, errors: {} },
+            getValues: () => elRef.value?.uploader.getValues() ?? {},
+            getFiles: () => elRef.value?.uploader.getFiles() ?? [],
+        });
+        return () => h("form-uploader", { ref: elRef });
+    },
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "form-uploader",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Reusable contact + multi-image upload form: framework-agnostic core and a drop-in custom element for any website.",
   "author": "Elbeg Darkhanbaatar",
   "repository": {
@@ -29,23 +29,51 @@
     "./element": {
       "types": "./dist/element.d.ts",
       "default": "./dist/element.js"
+    },
+    "./react": {
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    },
+    "./vue": {
+      "types": "./dist/vue.d.ts",
+      "default": "./dist/vue.js"
     }
   },
   "files": [
     "dist",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "tsc -p tsconfig.json && npm run build:browser",
+    "build:browser": "esbuild src/element.ts --bundle --format=iife --minify --outfile=dist/form-uploader.global.js",
     "test": "npm run build && node --test test/",
     "prepack": "npm run build",
     "format": "prettier --write .",
     "format:check": "prettier --check ."
   },
   "license": "MIT",
+  "peerDependencies": {
+    "react": ">=18",
+    "vue": "^3"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
   "devDependencies": {
+    "@types/react": "^19.3.0",
+    "esbuild": "^0.28.2",
+    "happy-dom": "^21.0.4",
     "prettier": "^3.9.10",
-    "typescript": "^7.0.2"
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "typescript": "^7.0.2",
+    "vue": "^3.5.45"
   }
 }