@dmitryvim/form-builder 0.2.27 → 0.2.28

package/README.md

@@ -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.