@dmitryvim/form-builder 0.2.26 → 0.2.28

package/README.md

@@ -54,7 +54,7 @@ This package ships with complete TypeScript definitions. Ensure your `tsconfig.j
 ## Core Features
 
 - **🎯 Schema-driven forms**: JSON Schema v0.3 → Interactive forms with live preview
-- **📁 Advanced file handling**: Images, videos, documents with drag-and-drop and grid preview
+- **📁 Advanced file handling**: Images, videos, documents with drag-and-drop, tile preview, and per-file upload progress
 - **✅ Real-time validation**: Client-side validation with visual feedback and error display
 - **🌍 Internationalization**: Built-in English/Russian support with extensible translation system
 - **🎨 Rich field types**: Text, textarea, number, select, file, files, and nested groups
@@ -301,8 +301,8 @@ See [Integration Guide](docs/integration.md) for detailed setup instructions.
 - **Colour**: Colour picker with hex values (single or palette)
 - **Slider**: Range slider with linear/exponential scales (v0.2.7+)
 - **Table**: 2D editable grid with cell merging, keyboard navigation, readonly mode
-- **File**: Single file upload with preview and type restrictions
-- **Files**: Multiple file upload with grid layout and drag-and-drop
+- **File**: Single file upload with compact dropzone, tile preview, and type restrictions
+- **Files**: Multiple file upload with 80px tile grid, per-file upload progress, and drag-and-drop
 - **Container**: Nested containers with repeatable array support
 
 ### File Handling
@@ -341,6 +341,19 @@ const form = createFormBuilder({
   getDownloadUrl?: (resourceId: string) => string | null,     // Optional: URL for downloading full file
   actionHandler?: (value: any, key: string, field: any) => void,
 
+  // v0.2.28: Host-owned file library picker (optional)
+  // When configured, adds an equal-prominence "From library" trigger alongside upload.
+  // resolve([]) = silent cancel; reject/throw = error shown in the field.
+  // PickedResource is exported from the package root.
+  pickExistingFiles?: (context: {
+    fieldPath: string;          // bracket-notation path, e.g. "slides[2].image"
+    mode: 'single' | 'multiple';
+    accept?: { extensions?: string[]; mime?: string[] };
+    maxSizeMB?: number;         // Infinity if no limit
+    remainingSlots?: number;    // multi mode only
+    selectedResourceIds?: string[];
+  }) => Promise<PickedResource[]>,
+
   // v0.2.0: onChange events
   onChange?: (formData: FormResult) => void,
   onFieldChange?: (fieldPath: string, value: any, formData: FormResult) => void,
@@ -510,6 +523,49 @@ When a user clicks the download button in readonly mode, the form builder uses t
 
 `getThumbnail` must be async (return `Promise`). TypeScript enforces this at compile-time. If you provide a synchronous handler, the error will occur at first file usage (not at form instantiation). This is intentional - we avoid validation calls that would trigger unnecessary API requests. Follow the **FAIL FAST** principle: errors surface naturally at usage.
 
+### File Library Picker (v0.2.28+)
+
+Let users pick from already-uploaded files without re-uploading. Configure the optional `pickExistingFiles` handler to open your own media library modal.
+
+```typescript
+import { createFormBuilder, PickedResource } from "@dmitryvim/form-builder";
+
+const form = createFormBuilder({
+  uploadFile: async (file) => "resource-id",
+
+  pickExistingFiles: async (ctx) => {
+    // ctx.fieldPath — bracket-notation path, e.g. "images[0].cover"
+    // ctx.mode — "single" | "multiple"
+    // ctx.accept — { extensions?, mime? }
+    // ctx.remainingSlots — multi mode: how many more files fit
+    // ctx.selectedResourceIds — IDs already in this field (for UI deselection)
+
+    const chosen = await openYourLibraryModal(ctx);
+    // resolve([]) to cancel silently
+    return chosen; // PickedResource[]
+  },
+});
+```
+
+**`PickedResource` interface:**
+
+```typescript
+interface PickedResource {
+  resourceId: string;
+  name: string;
+  type: string; // MIME type
+  size: number; // bytes
+}
+```
+
+**UI behavior:**
+
+- Without `pickExistingFiles`: no UI change (identical to v0.2.27).
+- With `pickExistingFiles`: empty state shows two equal cards (upload + library). Multi-file fields show two add-tiles ("+"/upload and library icon). Both are hidden when `maxCount` is reached.
+- Single-file with a file already selected: no library trigger (existing tile occupies slot).
+
+**Validation:** The library re-validates resolved items using the same rules as upload (`accept.extensions`, `maxSize`, `maxCount`, dedupe). Host-side filtering in your picker UI is advisory.
+
 ### Conditional Field Visibility
 
 Show or hide fields based on form data values using the `enableIf` property:
@@ -788,7 +844,7 @@ Features a 3-column interface:
 - **GitHub**: [picazru/form-builder](https://github.com/picazru/form-builder)
 - **NPM Package**: [@dmitryvim/form-builder](https://www.npmjs.com/package/@dmitryvim/form-builder)
 - **CDN**: [picaz-form-builder.website.yandexcloud.net](https://picaz-form-builder.website.yandexcloud.net/)
-- **Version**: 0.2.0 (Unreleased - Breaking Changes + New Features)
+- **Version**: 0.2.28
 - **License**: MIT - see [LICENSE](LICENSE) file
 
 Built with ❤️ for the web development community.